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Preface 



This manual describes ALLY release 2.0. 



This manual contains information for system managers on how 
to establish and maintain an ALLY environment on UNIX and 
MS-DOS systems. If you are running ALLY under another 
operating system, see the ALLY installation guide for your sys- 
tem. 

The manual has nine chapters and four appendixes. 

Chapter 1 explains ALLY'S directory structure and files, ALLY 
environment variables, AFILE naming conventions, paths to 
help and error AFILEs, and compatibility among ALLY 
releases. 

Chapter 2 describes how to invoke ALLY with commands and 
command files. 

Chapter 3 describes each section of ALLY'S Format File. 

Chapter 4 describes the key-definition file and shows an exam- 
ple. 

Chapter 5 discusses the terminal definition file and shows an 
example. 

Chapter 6 explains the Terminal Definer utility. 

Chapter 7 describes the printer definition file and shows an 
example. 

Chapter 8 explains the Printer Definer utility. 

Chapter 9 discusses how to route your printer output to different 
destinations. 

Appendix A lists ALLY subdirectories and the files they contain 
in the UNDC environment. 

Appendix B lists ALLY files in the MS-DOS environment. 

Appendix C lists the mnemonics for all ALLY commands. 
These mnemonics are used in Macro Utility text files and in the 
key-definition file. 
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Appendix D contains a table of the ASCII character set with 
decimal, hexadecimal, and octal codes. 



The ALLY Documentation— What to Read 



The following illustration shows you how the ALLY documenta- 
tion is organized. 

If you want to develop ALLY applications, we suggest that you 
start by reading the ALLY system's introductory brochure. Intro- 
duction to ALLY. Then, you can build the application in Building 
a Simple Application. 

If you want to install ALLY, you should read the installation 
guide for your system. 

Note that the documentation for the runtime system of ALLY 
includes only the installation guide for your system, ALLY Com- 
mand Reference Manual, and AMU User's Guide. 
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Conventions 



You should read carefully the description of documentation con- 
ventions before rpaH.ir.tr thi< 



i 

luauuig una manual. 



We use the following conventions in this manual: 



Single quotes ( l ') 
Boldface type (bold) 

Double quotes (" ") 



Brackets (<x>) 



Empty brackets (<>) 



Identify command names. 

Highlights text you are to enter. Boldface 
is also used within command syntax state- 
ments. 

Identify text strings within text sections. 
These strings are typically located in 
examples or as part of the prompts that 
ALLY sends to your display. 

Sometimes the exact content of a text 
string is affected by the traditional rules 
of punctuation. In these cases, we place 
the closing quotation mark at the end of 
the text string. For example, instead of: 

You see the prompt "Macro number:." 

We say: 

You see the prompt "Macro number:". 

Enclose a specific key (x = key) to be 
typed. Angle-brackets are used in com- 
mand syntax and key assignment lines. 
For example: 

<,> the "comma" key on the 

numeric keypad 
<Return> the "Return" key 
<Do> the "Do" key 
<F18> the "function" key 18 
<2> the "2" on the numeric 

keypad 

Represent a form that requires input in 
menu path sequences, e.g., 1 2 <> 3 4. 
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Space (< Space >) Represents a blank to be entered. A 

< Space > request asks you to type the 
space bar once. 

Square brackets ([]) Enclose an argument for the command- 
line invocation of a utility. For example, 
newprint [printer name] [output file]. 

The key-definition files that are supplied with ALLY assign keys 
to several commands. For convenience, we assume that the fol- 
lowing ALLY commands are assigned as shown. 



Command 


Kev Assignment 


"add new line 1 


< Return > 


'up' 


< f> 


'down' 


< i> 


'right' 


< ->> 


'left' 


<<-> 


'define macro' 


(See template) 



The < t>, < l>, <-*>, and <«-> key assignments typically 
use a terminal's cursor-control keys. 

End of Preface 
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Chapter 1 
The ALLY Environment 



Introduction 



This manual contains information for system managers on how to 
establish and maintain an ALLY environment under UNIX and 
MS-DOS. If you are running ALLY under another operating sys- 
tem, see the ALLY installation guide for your system. 

This chapter describes the following aspects of establishing and 
maintaining ALLY'S working environment: 

• the structure and contents of the ALLY system's directories 

• location of important files 

• environment variables 

• AFELE naming conventions 

• paths to help and error AFILEs 

• ALLY'S compatibility policy 



The ALLY Directory Structure 



Each ALLY release is stored in a directory named ally.r_vz, 
where x_yz is the release number. For example, the directory for 
ALLY Release 2.00 is named "ally2_00." The structure of the 
ALLY directory depends on the operating system you are using. 
The next two sections describe the directory structure for UNIX 
and MS-DOS. 
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The ALLY Directory Structure Under UNIX 

When you install ALLY Release 2.00 on a UNIX system, ALLY 
creates several subdirectories in the "ally2_00" directory. These 
subdirectories are listed in Table l-l. 



Table 1-1. Subdirectories in the ALLY Directory 



Subdirectory 


Contents 


/afiles/ 


Subdirectories that contain AFILEs that ALLY uses 


/allyexe/ 


ALLY executable files 


/bin/ 


Operating-system command files to invoke ALLY 




facilities 


/formats/ 


Format File used by ALLY utilities 


/objects/ * 


Compiled sample source code used by an external 




link that allows ALLY to communicate with a 




high-level language 


/printers/ 


Printer description files 


/src/ * 


A subdirectory that contains sample source code 




used by an external link that allows ALLY to com- 




municate with a high-level language 


/term/ 


Terminal definition files 



* Development systems only 



Figure 1-1 shows the structure of ALLY'S top-level directory 
under UNIX. 
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allyx_yz 



afiles 


allyexe 


bin 


formats 


objects 


printers 


src 


term 
















include 














1 


1 




allyedit 


amu 


commen 


dialog 


errors 


fcsdemo 


storybook 





* Development systems only 

F002-0893-00 

Figure 1-1. ALLY Directory Structure Under UNIX 

The files in these UNIX subdirectories are listed in Appendix A. 



The ALLY Directory Structure Under MS-DOS 

On MS-DOS systems ALLY creates only one directory. This 
directory is installed by default in the C: drive. The "\ally2_00" 
directory contains the files that are listed in Appendix B. 



ALLY Environment Variables 



You can assign the names of files used by your ALLY application 
to operating-system environment variables. When an application 
executes, ALLY looks for the variable's value in the operating 
system's environment variable assignments. 
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Environment variables allow you to specify short variable names 
instead of longer path names. It is easier to change an environ- 
ment variable's value than it is to change the value in an AFILE. 
Environment variables can also make your applications more tran- 
sportable across operating systems by minimizing changes due to 
syntax differences. 

Table 1-2 describes three operating-system environment variables 
that ALLY uses. 



Table 1-2. ALLY Environment Variables 



Variable 


Value 


ally 


The path, or search list, to the top-level 


ALLY directory 


TERM 


The name of a terminal type (e.g., svtl220) 


ally printer 


Overrides the default printer spooling 




device or queue name 



The "ally" environment variable is the path to the ALLY direc- 
tory. Therefore "ally" must be defined for each user process on 
UNIX systems and each time you reboot on MS-DOS. ALLY 
must also know what type of terminal you are using. ALLY can 
get this information from: 

• the "TERM" variable setting on UNIX systems. On MS- 
DOS systems, ALLY uses the "pcterm" terminal descrip- 
tion. 

• an argument to an ALLY invocation command. 

The "allyprinter" environment variable is described in Chapter 9. 
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Using Environment Variables 



You can specify environment variables for the following parts of 
an application: 

• help and error library AFILE names. 

• utility file names (e.g., the terminal definition and key- 
definition files). 

• data source file names for some access methods, including 
FX and C-ISAM. (See the developer notes for other access 
methods.) 

• print file characteristics for form/report packets. 

• global printer specifications (printer definition file, output 
file, spooling information). 

Using ALLY environment variables involves three steps: 

1) Displaying the values of environment variables. 

2) Defining the value of environment variables with 
operating-system commands before your ALLY applica- 
tion executes. 

3) Directing ALLY to use an environment variable by 
enclosing the name in braces in the Dialog. 

Displaying Environment Variables 



In standard UNIX installations, you can display the setting of an 
environment variable by typing the following command: 

echo $variable_name 

Table 1-3 lists the UNIX and MS-DOS commands used to display 
all of the environment variables that are defined for a user pro- 
cess. 
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Table 1-3. Commands to Display Environment Variables 



Defining Environment Variables 

Table 1-4 lists UNIX and MS-DOS commands used to define an 
environment variable. 

Table 1-4. Commands to Define Environment Variables 



Operating System Command 



The MS-DOS "set" command defines a variable for the duration 
of a PC session. If you include the "set variable = value" com- 
mand in an "autoexec.bat" file, the variable is automatically re- 
defined whenever you reboot the system. 

UNIX users can place the appropriate commands in the ".cshrc" 
(C-shell) file or ".login" (Bourne shell) file in their home direc- 
tories. 

After you have defined an environment variable's value with 
operating system commands, you direct ALLY to find an environ- 
ment variable by enclosing the name in braces during a Dialog 
session (Figure 1-2). 



Operating System Command 

UNIX Berkeley 4.x printenv 

UNIX System 5 env 

MS-DOS set 



UNIX C-shell 
UNIX Bourne shell 



setenv variable value 

variable — value 
export variable 
set variable = value 



MS-DOS 
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Changing an Environment Variable Name 

Suppose you want to run your application with a Format File in a 
different directory. You can do this by assigning an environment 
variable, for example "local," that contains the path to the new 
Format File. To use this Format File, type "{local}" as part of 
the name (Figure 1-2). 



Macro Utility 
Format File: {aUy>/fannafca/adJyfint 
Macro file: □ 
Text file: 
Deocmpile a macro: 
Compile a macro: 



Macro Utility 
Format File: -QocalVallyfnit 
Macro file: □ 
Text file: 
Deoanpile a macro: 
GciBpLT© & bbcpo: 



F002-0909-00 

Figure 1-2. Changing an Environment Variable Name 
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AFILE Naming Conventions 



Table 1-5 shows the conventions that ALLY uses to name dif- 
ferent types of AFILEs. 

Table 1-5. AFILE Naming Conventions 



AFILE Type 


Extension 


Application 


.a 


Error message 


.e 


Help message 


.h 



Using these conventions, here are some examples of how ALLY 
AFILEs are named: 

amu.a AFILE that contains the Application Maintenance 
Utilities (AMU) application 

amu.h AFILE that contains help messages for the AMU's 
forms and menus 

amu.e AFILE that contains error messages for AMU errors 

commen.h AFILE that contains help messages for command 
menus 

errors. e AFILE that contains error messages for general 
application-execution errors 



Paths to Help and Error AFILEs 

All ALLY applications can access a collection of general help and 
error messages. These messages are grouped in AFILEs called 
library AFILEs. 
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When creating an application, you start with an AFILE "skele- 
ton," called a trunk AFILE. The Dialog creates the trunk 
AFILE for you when you specify a new AFILE name. A trunk 
AFILE contains default paths to Dialog-specific help and error 
AFILEs. These AFILEs, in turn, point to ALLY'S general help 
and error AFILEs (see Figure 1-3). Note that every AFILE, 
including error AFILEs, can have both an error AFILE and a 
help AFILE. 



Errors 



Errors 



Trunk 
AFILE 



dialog.e 



errors. e 


Help^ 


commen.h 





Help 



commen.h 



Errors 



Help 
— ► 



dialog, h 



errors. e 



Help 



commen.h 



Errors 
► 



errors.e 



ALLY'S error AFILE for the Dialog is "dialog.e" 
ALLY'S general error AFILE is "errors.e" 
ALLY'S help AFILE for the Dialog is "dialog.h" 
ALLY'S help AFILE for command menus is "commen.h" 

F002-0830-00 

Figure 1-3. Paths to Help and Error Files in Trunk AFILEs 
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Changing Paths to Message AFlLEs 



You can create your own help message and error message 
AFILEs to provide messages specific to your application. Your 
application should point to its specific help and error AFILEs. 
These AFILEs should point to ALLY'S general help and error 
AFILEs. 

There are two ways to replace default paths with paths to user- 
defined message AFILEs: 

1) With Dialog forms in the "Maintaining and Managing 
Applications 1 ' branch. 

2) With special directives in a text file that the AFILE Mes- 
sage Builder utility uses to build a message AFILE. 



Changing Paths with the Dialog 



You can change paths to library AFILEs with application-specific 
paths by using two Dialog forms in the "Maintaining and Manag- 
ing Applications" branch (Figure 1-4). 



1 Application 
| Definition, 
I Maintenance, 
I & Management 



Security 
Information 



Global 
Information 



Help, Error, and 
Library AFILE 
Characteristics 



Library AFILE 
information — 
Help ABLE 



Runtime 
Diagnostic 
Options 



ALLY Utilities 



Integrity 
Report 



Library AFILE 
Information — 
Error AFILE 



F002-0901-00 



Figure 1-4. Changing Paths with the Dialog 
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Use the Library AFILE Information — Error AFILE form to 
change the path to your error AFILE. Use the Library AFILE 
Information — Help AFILE form to change the the path to your 
help AFILE. You can use these Dialog forms to change paths to 
message AFILEs in your application's AFILE or any of its mes- 
sage AFILEs. Refer to the Dialog User's Guide (UP- 12505) for 
more information. 



Changing Paths with Directives 



The AFILE Message Builder utility creates a message AFILE 
from a text message file. Unless you change the paths, this mes- 
sage AFILE is linked to ALLY'S general helps and errors. 

When you build an error or help AFILE for your application, you 
can include two special directives in the message text file. These 
directives signify the path and file name to additional error and 
help AFILEs. If you do not include these directives, your mes- 
sage AFILE is automatically linked to ALLY'S general help and 
error AFILEs. These directives are: 

$efn$ The path and file name of an error AFILE 

$hfn$ The path and file name of a help AFILE 

Refer to the Utilities User's Guide (UP- 12508) for more informa- 
tion about the AFCLE Message Builder. 



Paths to Application Message AFILEs 



Figure 1-5 shows the paths when an application has its own help 
and error AFILEs. 
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Application 
AFILE 





Application 
error AFILE 




Errors 


errors.e 




commen.h 






► 




Srrors 


application.e 












- — ► 


— ► 
















Help 
^ 


commen.h 


Errors^ 


errors.e 
































Errors 


errors.e 


Help^ 


commen.h 








| — » 




Help 
1 > 


application. h 


— ► 
























Application 




Help 


commen.h 


Errors 
► 


errors.e 




help AFILE 









ALLY'S general error AFILE is "errors.e" 

ALLY'S help AFILE for command menus is "commen.h" 

F002-0831-00 

Figure 1-5. Paths to Application Help and Error AFILEs 



If the paths to the library AFILEs are not complete, ALLY can- 
not find the message text when an error condition occurs or a user 
asks for help. Instead of message text, ALLY displays for: 

errors An internal ALLY number associated with the 
ALLY error condition 

helps An error message that ALLY cannot find the mes- 
sage text 
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Compatibility Among ALLY Releases 

Parts of ALLY applications, such as AFILEs and the Format 
File, have version numbers that ALLY checks. The ALLY 
installation guide for your system lists specific version numbers 
that are valid for your ALLY release. 

ALLY supports two types of compatibility: 

Upward compatibility Any new ALLY release can run any 

application AFILE built with an older 
ALLY release. 

Downward compatibility AFILEs created with new ALLY 

releases will execute under some older 
ALLY releases. 



Upward Compatibility 



When you execute the Dialog on an older application, ALLY asks 
you if you want to update the AFILE to the newer version 
number. If you respond by typing "Y<Return>," the AFELE is 
upgraded. You can also upgrade an AFILE with the AFILE 
Migrator utility or by compacting it with the AFILE Compactor 
utility. 



NOTE: Once the AFELE is upgraded, you may not be able to 
execute it with an older ALLY release. Therefore, you may 
want to make a back-up copy of the old version of an AFILE 
before converting it. . 
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You can transport applications from one operating system to 
another even if both systems are not running the same ALLY 
release. However, if you transport an AFILE between different 
ALLY releases that do not both support the data's access method, 
you may have to: 

• redefine the DSD 

• transport the data with the Data Migrator utility 



Downward Compatibility 



The AFILE Migrator utility will provide downward compatibility 
for releases after ALLY version 2.00. That is, you can use a 
release 2.+ AFILE Migrator to revert an AFILE to a lower 
release number. 

If you transport an AFILE to a lower release number, you should 
check the integrity of the whole application. The integrity report 
will list any elements (e.g., AFILE item types or ADL functions) 
that are not supported in the lower version AFILE. Figure 1-6 
shows the location of the Dialog form (Integrity Report) that you 
use to check your application's integrity. 



| Application 
| Definition 
| Maintenance. 
1 & Management 





Ubrary AFILE 
Characteristics 



Runtime 
Diagnostic: 
Options ; 
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Figure 1-6. Location of the Dialog Form for Integrity Reports 



End of Chapter 1 
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Introduction 



This chapter describes two methods for invoking ALLY and the 
ALLY utilities from your operating system. You can invoke 
ALLY: 

• with a command 

• with a command file 

A command invokes an ALLY executable file directly. A com- 
mand consists of the path and file name of an executable file, fol- 
lowed by required arguments. 

A command file also invokes an executable file. In addition, com- 
mand files check the arguments for validity, provide a default 
path to the executable file, and provide default values for some of 
the command's arguments. Because command files provide 
default values for arguments, they require less typing than com- 
mands do. 

Arguments to both commands and command files are positional. 
Specify "none" as a position "placeholder" for arguments that do 
not have a value (e.g., password or symbol table file). 

Figure 2-1 shows the relationship of commands and command 
files to the executable files that they invoke. 
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Command 



path and filename arg 1 arg 2 ...arg n 



Command File 



Default paths 

Default values for 
certain arguments 

Validity checking 
for argument values 



filename arg 1 arg 2 ... arg n 



Executable File 
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Figure 2-1. Commands and Command Files 



Using Commands 



When you invoke ALLY and its utilities with a command: 

• All of the command arguments are positional and required. 

• The executable file name, and any other argument that 
specifies a file, must include the file's path. 

On UNIX systems, these executable files are in the l 7allyexe/" 
subdirectory. On MS-DOS systems, the executable files have an 
extension of l \exe" and are in the "a\\yx_yz" directory (x_yz is 
the release number). 
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Using Command Files 



When you invoke ALLY and its utilities with the command files 
that are shipped with your ALLY release: 

• the arguments are positional. However some have defaults 
and are not required. Because the arguments are posi- 
tional, you must specify a value for each argument that pre- 
cedes the last one you want. 

• The default values for ALLY command files specify that 
AFILEs have internal symbol tables and are not password- 
protected (if you do not provide values for these argu- 
ments). 

• A command file provides a default path to the executable 
file. 

• A command file that invokes a utility uses the Format File 
installed with your ALLY release. 

• A command file provides a default value for the terminal 
description file, if the executable file requires one. 

• On UNIX systems, the command files are in the "/bin/" 
subdirectory and are written in the Bourne shell syntax. 
On MS-DOS systems, the command files have an extension 
of ".bat" and are in the "allyjr_vz" directory. 

• The "ally" environment variable must be defined before 
you invoke command files. 



Invoking ALLY 



This section describes the two versions of the ALLY execution 
system, and then shows the syntax of the commands and com- 
mand files that are shipped. The commands show the executable 
file names; note that they end with an "x." You can type a com- 
mand file name followed by the single argument "help" to display 
information about the arguments that have default values and are 
thus optional. 
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There are two versions of the ALLY execution system: the 
development system and the runtime system. 

The development system runs: 

• the Application Developer's Dialog 

• the ALLY utilities 

• any ALLY application 

• the ALLY Text Editor 
The runtime system: 

• runs any application built with the Dialog 

• does not run the Dialog; therefore users cannot change an 
application 

• runs the ALLY Text Editor 

• includes a set of utilities, called the Application Mainte- 
nance Utilities (AMU), that allows users to tailor applica- 
tions for different terminals and printers 

I nvoking an Application 

The following command runs an AFILE. 

allyrunx [terminal description file] [AFILE] [macro file] 
[entry point] [debug log] 

The arguments for this command are: 

terminal description file is the name of the file that contains 

information about your terminal. 

AFILE is the name of the AFILE that you 

want to run. 
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is the name of a file, defined in a pre- 
vious ALLY session, that contains 
ALLY keystrokes. This allows you to 
reuse macro files, rather than having 
to define macros in each session. 
Specify "none" if you do not want to 
include a macro file. 

is the name of the entry point in the 
application. By convention, 
"MAIN_TASK" is the name of the 
default entry point. 

is the name of the file to which you 
want the AFILE debugger messages 
written. The debugger selectively 
traces the execution of ALLY actions, 
tasks, and data transfers. Specify 
"none" if you do not want a debug 
log. 

The following command file runs an AFILE. 



ally [AFILE] [terminal description file] [entry point] 



Only the first argument is required, because the other two have 
defaults. 



Invoking the Dialog 



Because the Dialog is an ALLY application, the arguments to run 
the Dialog are the same as the arguments shown previously for 
running any application. The Dialog's AFILE name is 
"dialog.a." 



macro file 



entry point 



debug log 
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The following command invokes the Dialog: 



allydevx [terminal description file] /dialog.ay [macro file] 
/1MAIN_TASK/ [debug log] 



Type the name of the Dialog AFILE, preceded by its path, for 
the second argument. Note that the entry point must be 
"MAIN_TASK." 

The Dialog command file is: 



dialog [terminal description file] 



The terminal description file argument is optional because the 
default value is the same as your "TERM" environment variable. 



I nvoking the Application Maintenance Utilities 

The command to invoke the Application Maintenance Utilities 
(AMU) is: 



amux [terminal description file] /amu.a/ [macro file] 
/MAIN_TASK7 [debug log] 



Type the name of the AMU AFILE, preceded by its path, for the 
second argument. Note that the entry point must be 
"MAIN_TASK." 

The AMU command file is: 



amu [terminal description file] 



The terminal description file argument is optional. 
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Invoking ALLY Utilities 



This section shows the syntax of the commands and command 
files that are shipped with the ALLY utilities. The commands 
and the command files are listed below. 

See Chapter 6 and Chapter 8 for details about the arguments for 
the Terminal Definer and Printer Definer utilities. Refer to the 
Utilities User's Guide (UP- 12508) for details about arguments for 
the other utilities' command files. You can type a command file 
name followed by the single argument "help" to display informa- 
tion about the arguments that have default values and are thus 
optional. 



The AFILE Compactor 



The AFILE Compactor command is: 



compactx [Format File] [input AFILE] [output AFILE] 
[symbol table file] [password] [options] 



The AFILE Compactor command file and its arguments are: 



acompact [input AFILE] [output AFILE] [symbol table file] 
[password] [options] 



The last three arguments (symbol table file, password, and 
options) have default values. 
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The AFILE Merger 



The AFILE Merger command is: 



mergex [Format File] [master AFILE] [master AFILE 
password] [second AFILE] [second AFILE password] 
[output AFILE] [symbol table file] [output AFILE password] 
[options] 



The AFILE Merger command file and its arguments are: 



amerge [master AFILE] [master AFILE password] [second 
AFILE] [second AFILE password] [output AFILE] [symbol 
table file] [output AFILE password] [options] 



The last argument (options) has a default value. 



The AFILE Message Builder 



The AFILE Message Builder command is: 



newmsgx [Format File] [AFILE] [symbol table file] 
[password] [Dialog AFILE] [options] [text file(s)] 



The AFILE Message Builder command file and its arguments are: 



newmsg [AFILE] [options] [text file(s)] [password] [symbol 
table file] [Dialog AFILE] 



Note that the order of the arguments in the command is different 
from the order in the command file. This is because the com- 
mand file has default values for the password, symbol table file, 
and Dialog AFILE; thus these arguments are optional. 
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The AFILE Migrator 



The AFILE Migrator command is: 



amigratx [Format File] [input file] [output file] [symbol table 
or password] /V or wy [\i] 



The AFILE Migrator command file and its arguments are: 



am ig rate [input file] [output file] [symbol table or pass- 
word] [r or wy [y] 



The AFILE Script Writer 



The AFILE Script Writer command is: 



scriptx [Format File] [input AFILE] [output text file] 
[password] [options] 



The AFILE Script Writer command file and its arguments are: 



ascript [input AFILE] [output text file] [password] [options] 



The last two arguments (password and options) have default 
values. 



The Data Migrator 



The Data Migrator command is: 



dmigratx [terminal description file] [Format File] [AFILE] 
[password] [DSD name] [text file] [r or wy 
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The Data Migrator command file and its arguments are: 



dmigrafe [AFILE] [password] [DSD name] [text file] 
[r or w/ 



Note that the command file does not require the terminal descrip 
tion file argument. 



The Macro Utility 

The Macro Utility command is: 



mmigratx [Format File] [input file] [output file] [c or 6] 



The Macro Utility command file and its arguments are: 



mmigrate [input file] [output file] [c or 6] 



The Printer Definer 



The Printer Definer Command is: 



newprntx [Format File] [printer name] [output file] [printer 
definition file] 



The Printer Definer command file and its arguments are: 



newprint [printer name] [output file] 



Note that the command file does not require the printer definition 
file argument. 
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The Terminal Definer 



The Terminal Definer command is: 



newtermx [Format File] [terminal name] [output file] 
[key-definition file] [terminal definition file] [option] 



The Terminal Definer command file and its arguments are: 



newterm [terminal name] [output file] [key-definition file] 
[option] 



The last argument (option) has a default value. Note that the 
command file does not require the terminal definition file argu- 
ment. 



End of Chapter 2 
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The Format File 



The Format File contains the message text that the ALLY utilities 
produce. Error text and status messages are stored in the Format 
File and in ALLY'S error AFILE (errors. e). This simplifies 
translating ALLY applications to other languages, because you 
need to edit only the text in the Format File and the files used to 
build the "errors.e" AFILE. 

When ALLY is shipped, the Format File is named kk allyfmt.' , On 
UNIX systems, the Format File is in the "/formats/" subdirectory. 
On MS-DOS systems, the Format File is in the "ally.r_vz" direc- 
tory (x_yz is the release number). 

Before you attempt to make any changes to the Format File, 
make a copy so that you will always have a valid version. Even a 
change that appears innocuous (e.g., the addition of a blank char- 
acter) can prevent the utilities from functioning properly. 

Format File entries are associated with entry numbers and are 
separated by delimiter characters. You should never change the 
entry numbers, their positions, or the characters that delimit 
them. Changes to the text strings used in reports that the utilities 
produce are necessary only when you are translating the applica- 
tion to another language. 



Syntax of the Format File 



Figure 3-1 shows the beginning of a Format File as it is shipped 
with ALLY. 
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"' © 




COPYRIOn" 1985, 1986, 1987, 1988 Foundation Oanputer Systems 
This software contains confidential and. proprietary — ^ 
infannatian of Foundation Computer Systems, Inc. [2 J 


Set 0 




Error AFTLE path name 




1 1 /{ally}/afiles/errors/errars . e 1 (T) 




End of set 0 




III III (T) 
Set 1 




Beginning of strings used by the AFTTF, Compactor 
1 3 1 Statistics (storage in bytes) : 1 
141 Displayed teoctl 
151 Displayed text highlighting 1 
161 Items 1 A comment could go here 

(Lh © \ _ 
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Figure 3-1. Syntax of a Format File 



1) The first three characters in a Format File are the delim- 
iter characters. The vertical bar character (I) is the del- 
imiter in the Format File that is shipped with ALLY. 

All three delimiters can be the same or different charac- 
ters. Do not use delimiter characters that you might use 
as text in entries or comments. 

2) Anything after these initial three delimiter characters, up 
to the next start delimiter, is treated as a comment. 

3) The Format File is made up of several sections (called 
sets) that contain entries. The entry for the first section 
(Set 0) must be the path and file name to ALLY'S errors 
AFILE, shown here for UNIX systems. The utilities 
need this path in order to produce the text for error con- 
ditions that can arise. 
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4) Each set begins with the three delimiter characters and 
ends with the same three delimiter characters that began 
it. By convention, the three delimiters that end a set and 
the three delimiters that start the next set are on the 
same line. 

5) Each entry contains: 

6) the first delimiter character, followed by an entry 
number. 

7) a delimiter character after the entry number, indi- 
cating the start of the entry. 

8) a delimiter character after the entry, that indicates 
the end-of- entry and the start of an optional com- 
ment. 

The next characters can be either comments or the delimiters for 
the next section. (Space or text between two sets of delimiters is 
treated as a comment.) The delimiters do not have to be the 
same as those of the previous section. 

Although you can change the entry text, you cannot change the 
entry number or the item that is associated with the number. The 
parts of a Format File that you must not change are: 

• delimiters, once you have defined them 

• entry numbers 

• any specials symbols that are not in a comment 

Table 3-1 lists the sections (sets) of the Format File that are pro- 
vided with ALLY and the utilities that use them. 
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Table 3-1. Sections of the Format File 



Set Number 


Used bv 




... . 
All utilities 


i 
i 


The A FILE Compactor 


•} 


i ne ArlLfc. ocnpt writer 


3 


The AFILE Script Writer 


4 


The Terminal and Printer Definers 


5 


The AFILE Message Builder 


6 


(reserved) 


7 


The AFILE Merger 


8 


The Macro Utility 


9 


The A FILE Migrator 


10 


The Data Migrator 


11 


The AFILE Script Writer 



AFILE Compactor Section 



The AFILE Compactor uses set 1 of the Format File 
(Figure 3-2). Entries in set 1 provide the text for the statistics 
report that the AFILE Compactor produces. 
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Set 1 

Beginning of strings used by the AFILE Ccrnpactar 
lOlundefined I 
111. I 
121 

I 

1 3 1 Statistics (storage in bytes) : I 

141 Displayed text I 

151 Displayed text highlighting I 

161 Items I 

171 ADL streams I 

181 First block I 

191 Used I 

1101 Empty I 

1111 Total onnpar-tvfvi file size I 

1121 Character strings I 

1131 Symbol* I 

1141 Back pointers I 

1 15 1 none I 



Figure 3-2. Sample AFILE Compactor Section 



AFILE Merger Section 



The AFILE Merger utility uses set 7 of the Format File (Figure 
3-3). For the most part, the AFILE Merger entries provide the 
text for the messages that report global information differences in 
the two AFILEs being merged. 
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Set 7 

Beginning of strings used by the AFTTE Merger 

lOICharacter sorting sets are different 
lllnonel 

1 2 1 SYSIEMJEEEURriY I 

I 3 I Difference in num_parse_charB 

14 1 A non-aantexb was encountered vihen. a. context was expected 

1 5 1 Input AFTLE 1 is not at the current A FTTF version level I 

16 1 Input AFTTE 2 is not at the current AFTTF, version level I 

171 One or mare differences found in first blocks of input AFTTEb 

l8ldobal variable conflict I 

l9IEntry point conflict I 

I10l**unused**l 

*** Difference in first block detected by AMOGAF *** 
1 11 1 **unused** I 

1 12 1 Difference in machine_flags 

1 13 1 Difference in num_vnLbuffers 

1 14 1 Difference in help_infol 

I 15 I Difference in errar_infol 

1 16 1 Difference in spool_device I 

1 17 1 Difference in printer-description 

1 18 1 Difference in print_f ile I 

1 19 1 Difference in globaljpenu_£ype 

1 20 1 Difference in path^separatar 

1 21 1 Difference in prev_stringl 

1 22 1 Difference 

1 23 1 Difference in mirr\ jt\ JVi L c hars I 

1 24 1 Difference in nunujutJfrifrjharB I 

1 25 1 Difference in def _num_attr I 

1 26 1 Difference in def _char_attr I 

1 27 1 Difference in num_def _val I 

1 23 1 Difference in char_def _yal I 

1 29 1 Difference in date_def _yal I 

1 30 1 Difference in logan_petl 

1 31 1 Difference in arithtnetic^flags I 

1 32 1 Difference in sec_retriesl 

1 33 1 Difference in glocal^control^flags I 

1 34 1 Difference in menu_jpram3t_size I 

1 35 1 Difference in def _date_masks I 

1 35 1 Difference in date_strings I 

I37l**unused**l 

*** Messages related to integrity check *** 
1 39 1 Integrity errors found in AFILE 
End of strings used by the AFILE Merger 

I I I I I I 



Figure 3-3. Sample AFILE Merger Section 
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AFILE Message Builder Section 



The AFILE Message Builder utility uses set 5 of the Format File. 
Set 5 entries: 

• define defaults for message AFILE structures and values 
that are constant for most applications at a site 

• define special strings, called directives, that control 
highlighting or signify the type, beginning, and end of each 
message 

• provide default values for invocation command arguments, 
such as "none" for an external symbol table file or pass- 
word 

• provide special directives for paths to user-defined help and 
error AFILEs that override default paths to ALLY'S helps 
and errors 

When the Message Builder creates a message AFILE from an 
input text file, that AFILE has: 

• error message text for each message in the text file that 
starts with the "$e$" directive 

• help message text for each message in the text file that 
starts with the "$h$" directive 

• embedded string text for each message that starts with the 
"$s$" directive 

• legend text for each message that starts with the "$1$" 
directive 

The text is displayed exactly as it is entered in the input text file, 
except that the directives and control characters (other than "tab" 
and "newline") are removed. It is a good idea to limit the length 
of all lines to eighty characters to eliminate difficulty when: 

• working with text editors that have an eighty-column length 
limitation. (ALLYedit does not have this limitation.) 

• transporting message files to different computer systems. 
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Each error message, help message, embedded string, and legend 
must be assigned the same number as the internal AFILE number 
of an event that calls the message. The message number (or 
numbers) is specified after the message start directive ("$e$," 
"ShS; 1 or "$1$"). 

You can associate a message with more than one number, so that 
the same message can be used by many fields, menus, choices, or 
forms/reports. The number(s) must be the first characters after 
the start directive and must be specified on one line, unless a con- 
tinuation character is present at the end of the first line. The con- 
tinuation character is defined by entry 49, which is a back slash 
(\) in the Format File that is shipped with ALLY. Separate the 
message numbers with the character specified by entry 122, which 
is the message header number separator. Entry 122 is a space in 
the Format File that is shipped with ALLY. Do not specify dupli- 
cate message numbers. 



Directives for Message Text Type 



Set 5 entries 1 through 3, 67, and 124 are directives that identify 
text as either a help or error message, a legend, or an embedded 
string. Entry 67 is the directive for assigning a second-level help 
message (a help message for a help message). Entry 4 is the 
directive that signals the end of the message. These entries are 
shown in Figure 3-4. 

The numbers that follow these message type directives are those 
that you have assigned as help, error, and legend numbers for 
parts of your application. Directive 34 specifies the default help 
number assigned to help and error messages that do not have an 
explicitly assigned message number. 
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lll$e$ error header 
1 2 1 $e$ I anbedded string header 
I3l$h$lhelp header 
I4l$*$lend of message 

1 34 1 32764 1 farm/report help number 

I67l$help$lmes8age help_number 

11241$!$ I legend header 



Figure 3-4. Set 5 Entries for Message Type 



Directives for Paths to Error and Help AFILEs 

The Format File provides default paths and file names to ALLY'S 
general error and help AFILEs. The AFILE Message Builder 
uses these default paths when it builds message AFILEs. The 
default path to ALLY'S general error AFILE is entry 83. The 
default path to ALLY'S general help file is entry 84. Figure 3-5 
shows entries 83 and 84 from Set 5 in the Format File for UNIX 
systems. 



1 83 1 {ally}/af iles/errars/errt 


ars.e error AFILE 


1 84 1 {ally}/af iles/cxsmen/ocm 


nen.h help AFILE 



Figure 3-5. Format File Entries 83 and 84 from Set 5 



You can change the default paths to user-defined error and help 
AFILEs by including special directives that override these defaults 
at the beginning of your text file for input to the Message Builder 
utility. This establishes paths from the application's help and 
error AFILEs to ALLY'S general help and error AFILEs. The 
overriding directive for a user-defined error AFILE is entry 56. 
The overriding directive for a user-defined help AFILE is entry 
63. Figure 3-6 shows entries 56 and 63 from Set 5 in the Format 
File for UNIX systems. 
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I56l$e£n$l I directive far user-defined error AFUJE 
I63l$hfn$l I directive far user-defined help AFILE 



Figure 3-6. Format File Entries 56 and 63 from Set 5 



AFILE Migrator Section 



The AFILE Migrator section of the Format File is set 9 (Figure 
3-7). 



Set 9 

Beginning of strings used by the AFILE Migrator 

1 01 AFILE item name, AFILE item type, AFILE version number I 
I1ID6D AFILE item name, access method number I 
I2l**unused**l 

I3lnanel no external symbol table file 
141, I 

151 . 1 

I6IN0NAMSI 
l7IThe I 

1 81 version of the AFILE Migrator did not recognize the I 

access method of the following D6D AFILE items. 

The DSD AFILE items are from an AFLLE with version number I 

l9IFar a description of the access method number, see the documentation 
far the version of ALLY that supports version ! 

1101 AFLLEb.I 

1 11 1 The AFLLE contains the following unrecognized types of AFLLE items. 
Far a description of the following item type numbers, 
see the documentation far the version of ALLY that supports the AFLLE 
version number listed. I 

End of strings far the AFLLE Migrator 

Illlll 



Figure 3-7. Sample AFILE Migrator Section 
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AFILE Script Writer Sections 



The AFILE Script Writer sections of the Format File are: 
Set 2 Contains ALLY internal item names 
Set 3 Contains error messages 

Set 11 Contains control strings that govern Script Writer 
execution and the text for Script Writer output 

You can change only the ASCII text strings in set 1 1 that are used 
to produce Script Writer reports. Figure 3-8 shows part of the 
Script Writer's section 1 1 . 



Set 11 

Beginning of strings used by the AFILE Script Writer 



M3NU|5 

$7$ ($10$) 
$647$$36$ 

DtiveLaper comment: $32$% $15$ $515$$36$ 

$33$R$37$ 

No text defined far this menuJJ 



Menu window: ($506$.$5O7$) to ($506$, $509$) 
Prompt area: ($511$, $512$) to ($513$,$514$)$510$$51$ 
$550$Menu-Stjrle Cations Set: $58$$0$ 

- Numeric menu /$$58$$1$ 

- Function-key menu JS$58$$2$ 

- C u rsor-roam menu /S$58$$3$ 

- Letter menu fl$58$$4$ 

- Ward menu 5S$S8$$5$ 

- Roam highlighting J8$58$$6$ 

- Case sensitive 5j$58$$7$ 

- Minimal match /8$58$$8$ 

- Junping allowed JS$58$$9$ 

- Paths allowed /5$58$$10$ 



Figure 3-8. Sample AFILE Script Writer Section 
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Data Migrator Section 



The Data Migrator uses set 10 of the Format File (Figure 3-9). 
These text strings produce the descriptions of the elements in a 
DSD. 



Set 10 

Beginning cf strings used by the Data Migrator utility 



1121), I 
1131) I 

I14IM4/EDAYYY »E4:MI:SSI 

1 15 1 continuing without date strings 

I 

I16IFIHATI 
I17IFTXI 

I18ITRAILING BLANKS 

1 19 1 Item pointer I 

1 2D I String pointer I 

1 21 1 References 1 byte flag I 

1 22 1 References 2 byte flag I 

I23IAFHE 

I 

1 24 1 references bit I 
1251 negative logic I 
1251 positive logic I 
1 27 1 muter format I 
1281 width I 
1291 precision I 
1 30 1 string format I 
1311 length I 
1 32 1 date picture I 
1 33 1 Call type number I 
l34IAptr to an action I 



Figure 3-9. Sample Data Migrator Section 
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Macro Utility Section 



The Macro Utility uses set 8 of the Format File (Figure 3-10). 
Most of these text strings are the names of ALLY commands. 



Set 8 

Beginning of strings used by the Mvno Utility 

IOI?l 
lll?l 
121 ? I 
I3I?I 

l4IABDRTACnQNI 

i5iExmcnmi 

I6IAB0RTEASKI 

l7IEXITEAaCI 

I8IABCREAFFLI 

I9IE XTTAFPL I 

IIOIHEFHESHI 

I11IKELPI 

1 12 1 SHELL 

1 131 SET_PEFEAT_CNTI 

I14IFRNIS31NI 

I15IFRNTVNLMI 

I16IEXPAMM3WI 

I17I0CMTCSSWEWI 

I18IMJVEMWI 

I19IDEFINEWDWI 

I20ISOOLJNDWI 

121 IEXPLCEO/EWI 

I22IEES1ZBIOVI 

I23IDBFMAOOI 

I24IMACRFILEI 

I25IMWIMTLEI 

I2BISAVEMACRCEI 

I27ILQAEMACRDS 

I28IEXEMAO0I 

I29IEXEMAC1I 



Figure 3-10. Sample Macro Utility Section 
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Terminal and Printer Definer Section 

The Terminal Definer and Printer Definer share set 4 of the For- 
mat File (Figure 3-11). Most of the text strings in set 4 describe 
problems that prevent the terminal or printer description files 
from being created. 



Set 4 

Beginning of strings used by the Terminal Definer and Printer Definer utilities 



IOIWARNDC: I 

I1IEHRCR : I 

I2lkeyname I 

131 in. line number I 

141 in keydef file I 

1 51 invalid octal character 

1 61 invalid *Qar *S dn control sequence numbers I 

171 has incorrect format I 

1 8 1 execution stopping I 

ISJItey conflict I 

1101 at lines I 

1111 and I 

1121 not found I 

I13lterminal I 

1141 I 

1 151 line number I 

1161 cannot open termdef database file I 

1171 nob found in termdef database I 

I18l**unused**l 

1 19 1 cannot open output file I 

1 3D I printer I 

1211 not in printdef database I 

1221 cannot open key definition file: I 

End of strings used by the Terminal Definer and Printer Definer utilities 

I I I I I I 



Figure 3-11. Sample Terminal and Printer Definer Section 



End of Chapter 3 
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ALLY provides extensive support for keyboards. Because ALLY 
commands can be assigned to different keys or key sequences, 
ALLY and ALLY applications are as independent of keyboards 
as they are of terminals and printers. 

A key-definition file assigns commands to terminal keys. The 
Terminal Definer utility uses the key-definition file to build a 
terminal-description file that defines the terminal to ALLY. 
There must be a key-definition file for each terminal on which 
ALLY executes. Key-definition files for several terminals are 
included in your ALLY release. 



Command-to-Key Assignments 



You can assign any ALLY command to any terminal key or keys. 
You make these key assignments in a key-definition file. 

Each key on an asynchronous terminal sends one or more octal 
codes to the operating system. The terminal manufacturer deter- 
mines the code or sequence of codes that a key transmits. The 
documentation supplied by the terminal manufacturer lists the 
octal code(s) transmitted by each key. You assign a command to 
a key or keys by specifying in the key-definition file the 
mnemonic for the command next to the octal code for one or 
more keys. 

Certain keys are defined to be used in combination with another 
key; that is, you type one key and while pressing it, you type 
another key. The "Ctrl" key is often used in combination with 
another key in this fashion. 

You can also assign commands to a key combination, or to a 
series of keys, where you type one key and then type another key. 
For example, suppose the command to refresh the terminal screen 
is assigned to the key series, <PF1> and <PF2>. To invoke the 
'refresh' command, you first type <PF1> and then type <PF2>, 
instead of continuing to press <PF1> while you type <PF2>. 
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It is useful to understand all of the ALLY commands that can be 
invoked by key. A list of ALLY command mnemonics is 
included in Appendix C. You can refer to the ALLY Command 
Reference Manual (UP- 12509) for a complete description of each 
ALLY command. 



Syntax of a Key-Definition File 



Because there are more ALLY commands than keys, ALLY pro- 
vides key-definition files with the most commonly used commands 
assigned to keys. The remaining commands can be used through 
the Command Menus. However, you must assign the 'do' com- 
mand to a key in order to access the Command Menus. 

There are eight sections in a key-definition file. The first two are 
global sections that affect the remaining six local sections. Key 
assignments in a local section apply only to that section. There- 
fore, different commands can be assigned to the same key (or 
keys) from one local section to another. It is important to note 
that a key can have a different command assigned to it for dif- 
ferent ALLY subsystems (e.g., menus, forms/reports, 
ALLYedit). 

For example, <Return> can invoke the 'next field' command in 
forms/reports and the 'add new line' command in ALLYedit 
because the commands are in different local sections of the key- 
definition file. 

The syntax rules for a key-definition file are: 

• Each mnemonic must be followed by a colon (:). 

• The octal code or code sequence for the key (or keys) that 
invokes the command must follow the colon. 

• A line that begins with a semicolon (;) is a comment. 

• Each section must terminate with an "at" sign ((cv) at the 
beginning of a line. 

Figure 4-1 shows the format of a key-definition file. The Termi- 
nal Definer displays an error message if the key-definition file 
deviates from the correct format. A complete key-definition file 
is included at the end of this chapter. 
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WINDOW COMAND6 
Punctd.cn Octal Code 



Key Assignment 



winup: 

winright: 
winleft: 
windcne: 
0 

Mnemonic 



033 133 101 
033 133 102 
033 133 103 
033 133 104 
015 



Key assignment 



up 

dcroi arrow 
right arrow 
left arrow 
carriage return 



Comment 



Figure 4-1. Sample Entries in a Key-Definition File 



Sections of a Key-Definition File 

The sections of the key-definition file are arranged in the follow- 
ing order: 

• global flag definitions and scroll percentage 

• global commands 

• text editing commands 

• form/report commands 

• window commands 

• menu cursor roam commands 

• menu function task commands 

• menu prompt line terminators 

Each section is briefly described in the following pages. 



Global Flag Definitions and Scroll Percentage Section 

The commands in this section are global to ALLY and are not 
active commands. Rather, they are flags and variables that 
specify initial settings for things such as case sensitivity for search- 
ing and the amount to scroll a page when editing. The OFF set- 
ting for these flags and variables is octal 000 and the ON setting is 
octal 001. The default for the scroll percentage variable is 012, 
which leaves ten percent of the screen on page scroll (Figure 4-2). 
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F002-0563-00 

Figure 4-2. Scroll Percentage 



Global Commands Section 



The global commands in this section: 

• invoke macros and help messages 

• activate and manipulate tasks, including Command Menus 

• abort and exit from an action, a task, and an application 

They are called global commands because they can be used in any 
ALLY subsystem (text editor, image editor, form/report, etc.). 



Text Editing Commands Section 

These text editing commands apply whether you are editing a text 
file or a field in an ALLY application. 



Form/Report Commands Section 

ALLY forms and reports are unified and use the commands in 
this section. 



Window Commands Section 



These commands are for changing window size or location, and 
for moving the cursor within windows (e.g., 'scroll window'). 
Window commands are typically assigned to the four arrow keys 
and the "Return" key. 
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Menu Cursor Roam Commands Section 



These commands allow users to move among menu choices when 
in menu-roam mode. These commands are usually assigned to 
the four arrow keys. 



Menu Function Task Commands Section 



These commands allow users to make menu choices with function 
keys. 



Menu Prompt Line Terminators Section 



These commands specify how the user can exit from the menu's 
prompt line. Users can go to the first or last roam-mode choice 
(if that mode is active), pick a choice, or go to the previous or top 
menu. 

Conflicts in 

Command-to-Key Assignments 

The Terminal Definer displays error or warning messages if there 
are conflicts in key assignments (i.e., two or more commands are 
assigned to the same key or keys). Note that an error or warning 
is issued if the complete command assigned to one key is the same 
as the beginning of a command assigned to another key. For 
example, the following command assignments are in conflict with 
each other: 

exemacO: 004 013 
exemacl: 004 013 010 

An error message is issued if there are key-assignment conflicts 
between a command in a global section and any other section in 
the key-definition file. A warning message is issued if there are 
key- assignment conflicts between commands within a section or 
between local sections. 
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It is important to note that a key can have a different command 
assigned to it for different ALLY subsystems. However, 
command-to-key assignments in global sections take precedence 
over local key assignments. 

You can assign the same command to more than one key (or set 
of keys) within a section. This allows the user to choose what 
keys to use when invoking the command. The following example 
shows the 'find' command assigned to two different keys. 



fi«i:033 117 122; PF3 
find:033 133 061 176; Find key 



A conflict occurs when a key (or given set of keys) has more than 
one command assigned to it. It is acceptable to have conflicts 
among sections and even within sections; however, key-assignment 
conflicts can cause some commands to become unavailable. 

The rules for resolving key-assignment conflicts are: 

• The commands in global sections of a key-definition file 
supercede those in any other section. Thus, if a command 
in the form/report section and a command in the global sec- 
tion are assigned to the same key (or keys), the global com- 
mand assignment overrides the form/report command 
assignment. 

• If you assign more than one command to the same key (or 
keys) within a section of the key-definition file, the first 
command assignment overrides any later assignments to 
that key within the section. 

• If you assign a window command and another local com- 
mand to the same key (or keys), the window command is 
invoked only when you type the key while in a window 
command function. 

For example, if 'window up' (window command) and 'up' 
(text editing command) share a key assignment, 'window 
up' is invoked only if the preceding command invoked a 
window operation ('scroll window', 'resize window', or 
'move window'). 

Do not assign commands to *Q (<Ctrl>Q) and "S (<Ctrl>S), 
because the octal codes associated with *Q (021) and *S (023) are 
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part of the XON/XOFF protocol that ALLY uses to coordinate 
input and output with terminals. The Terminal Definer displays 
an error message and ignores a command assigned to a key that 
has 021 or 023 in its octal sequence. Also, because ALLY 
ignores the ASCII NUL character (octal 000), do not include the 
NUL character in key sequences. 



Comments in a Key-Definition File 

In a key-definition file, everything on a line following a semicolon 
(;) is treated as a comment and is ignored by the Terminal 
Definer. The comment symbol can be placed anywhere on the 
line. 

The following example shows two placements of the comment 
symbol. First, all heading lines are commented out. On the last 
line, the Terminal Definer processes the mnemonic and octal code 
for the 'help' command but ignores the key assignment comment. 



; Function Octal Code 


Key Assignment. 


; GLOBAL CDVMMCB 




khelp: 001 OlO 


;-A"H 



Figure 4-3. Comments in a Key-Definition File 



The Ignore Command 



You can assign the ignore' command to any key or sequence of 
keys that you want ALLY to ignore. Normally, when a key is 
pressed that is not assigned to an ALLY command, the key's 
octal sequence is displayed. However, when you press a key that 
is assigned the 'ignore' command, no action is taken and the 
display remains unaltered. This is useful when you want to leave 
a key without a command assignment. The ignore command can 
be assigned to keys in any section in the key-definition file. The 
following example shows how to assign the ignore command to 
the delete key. 
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ignore: 177 ; delete key 



The ignore command's action depends on whether it is assigned in 
a global section or in a local section. 

• A key assigned the ignore command in a global section is 
ignored throughout the application. 

• A key assigned the ignore command in a local section is 
ignored only in that section. 



Making Commands Unavailable to Users 

You may not want a particular command to be available because 
it is not appropriate for your application. You can make a com- 
mand unavailable to an application user with the key-definition 
file by: 

• not assigning the command to a key 

• assigning the ignore command to the key usually assigned 
to the command 

• preceding the command mnemonic with a semicolon, which 
makes the key-to-command assignment a comment 

In this example, the second key assignment for the 'expand win- 
dow' command is commented out. (However, the user can still 
use the command through ALLY's Command Menus.) 



expandwdw: 001 005 ; "A~V 

;expar«±wdw: 033 137 113 033 134 ; shift F3 
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User-Defined Key-Definition Files 



You can define your own key-definition files by editing a copy of 
the key-definition file that is shipped with ALLY. Key-definition 
files that you define and store in a different directory are 
preserved when you install a new ALLY release. 



Sample Key-Definition File 



The command- to- key assignments in the following key-definition 
file are for a Unisys SVT-1220 terminal. The assignments were 
made for use by ALLY developers, so this key-definition file may 
differ from one used in a production environment: 

• All commands in the list are defined — something few appli- 
cation users require. 

• Many of the commands are assigned to obscure control 
character sequences (combinations of control character 
keys) . 

• Assumes that the SVT-1220's numeric keypad is in applica- 
tion mode rather than numeric mode (i.e., that keys send 
escape sequences, instead of numbers, when typed). 
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O0PYRIGHT: 1985, 1986, 1987, 1988 Foundatd.cn Computer Systems, Inc. 

This software contains conf idential and proprietary 
infcEinatd.cn of Foundation Canputer Systems, Inc. 

ALLY Key definitions: sample key-definition file 

Standard key assignments far Unisys SVT-1220 terminals 
UNIX Version Foundation Computer Systems 

BFOKEANT NDIE: 

The arrow keys and the home key can transmit mare than cne octal 
code sequence. Any ALLY command assigned to these keys must be 
defined far all octal sequences that these keys can transmit. 

Function Octal Code Key Assignment 



GLOBAL FLAG DhKiNlllLTE AM) SCROLL H5RCENEAGE 



overtype: 


000 


overtype off 




ponertype: 


000 


powsrtype off 




dranmode: 


000 


draw mnde off 




casesense: 


001 


case sensitive 








search en 




findremain: 


001 


don't move cursor 








if find fails 




fdndtoend: 


000 


find end of string 








off 




clearfield: 


001 


clear fields before 








inserting 




scrollprcnt: 


012 


leave 10% of screen 








on page scroll 




; The "0" maz 


ks the end of the first global section 




'; GLOBAL COAiMBS 






khelp: 


001 010 


"AH 




khelp: 


033 133 082 070 176 


Help key 




g} v ir*t"a/— tvi m * 


003 001 


~C~A 




exLtaction: 


003 005 


"C*E 




abarttask: 


003 003 001 


~C~C~A 




exittask: 


003 003 005 


~C~C~E 




abartappl: 


003 003 003 001 


~C~C~C~A 




exitappl: 


003 003 003 005 


~C~C~C~E 


continued 
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shell: 


033 117 120 033 117 167 


PF1 7 


shell: 


003 010 , 


~CH 


refresh: 


001 032 


"A"Z 


setarpfcoit: 


033 117 121 


PF2 


pmfcvnuni: 


001 026 


~A~V 


pmtscrn: 


001 020 


"A"P 


piiiLscin: 


033 120 


ESC P 


expandwdw: 


001 006 


"A~E 


defiiuAKlw: 


001 004 


"A"D 


mnpresmwdiw : 


001 003 


~A~C 


mover 




001 015 


~A~M 


scroll wdw: 


001 014 


~A~L 


gxplodewlw: 


001 030 


~A~X 


resizendsr: 


001 022 


~A~R 


toggletask: 


001 061 015 


~A1~M 


toggletask: 


033 117 115 


Biter 


pLcktask: 


024 020 


T*P 


p&cktask: 


033 117 120 033 117 115 


PF1 ENIER 




004 014 


~D~L 


mactafile: 


004 027 


"D~W 


TTCV Pin Pt 1 ^ ; 


004 022 


~D~R 


savemacros: 


004 013 


~D"K 


loadnacros: 


004 007 


"D~G 


690ECE 


icO: 


005 060 


"ED 




icl: 


005 061 


"El 


eXBDE 


»c2: 


006 062 


~E2 


eXBDE 


ic3: 


005 063 


~E3 


exmt 


io4: 


005 064 


~E4 




ic5: 


005 065 


~E5 


GXEOE 


ic6: 


005 066 


• ~EB 


€MHIUf*7 : 


005 067 


; ~E7 


eautuic 


noB: 


005 070 


~EB 


eXBDE 


ic9: 


005 071 


~E9 




005 006 


; *ETF 


task 




001 003 013 061 


; DO key 


task 




002 003 013 062 


; XA9C menu 


task 




003 003 013 063 


fcENU menu 


task 




004 003 013 064 


; FCRM/SEPOKT menu 


task 




006 003 013 065 


; TEXT EDIT menu 


task 




006 003 013 066 


; WDSXJH menu 
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task 


007 


003 013 057 


task 


025 


024 061 


task 


026 


024 062 


task 


027 


024 053 


task 


oao 


024 054 


task 


031 


024 065 


task 


032 


024 056 


task 


033 


024 067 


task 


034 


024 070 


task 


035 


004 071 


e 







TEXT EDITING CO/MANDS 



addnl: 

bdelefce: 

bol: 

bofctjcm: 

bene: 

clrcasesens 

clrdraasnrxLe 

drovertype 

clrjrortype: 

cpfronifciuf : 

uvei'layblk: 

ov«dilayblk : 

cptobuf : 

ctrlchar: 

delbol: 

deleol: 

djeXline: 

delfccmark: 

delwuid: 

duwti: 

donn: 

donnpage: 
eol: 

f delete: 

find: 

find: 

findanddel: 
findanddel: 



015 
177 

033 117 
033 117 
002 

017 003 
017 004 
017 017 
017 020 
033 117 
017 014 
033 133 
033 117 
003 017 
033 117 
033 117 
033 117 
033 117 
033 117 
033 117 
033 133 
033 117 
033 133 
033 117 
033 117 
033 117 
033 133 
017 006 
033 133 



163 

120 033 117 164 

003 
003 
003 
003 

120 033 117 166 
003 

063 062 176 
120 033 117 170 

120 033 117 163 

120 033 117 162 

123 

166 

155 

102 

102 

164 

066 176 
162 
154 
122 

061 176 
004 

063 176 



MACRO 
taskl key 
task2 key 
task3 key 
task4 key 
task5 key 
taak6 key 
task? key 
taskS key 
task9 key 



return 
EEL 

3 - ESC 0 s 

FF1 4 

~B 

TTC-C 
"CTD-C 
TT0-C 
TTC-C 
FF1 6 
-0~L-C 
F18 key 
FF1 8 
~C~0 
PF1 3 
PF1 2 
PF4 
6 

donn arrow 
donn arrow 
4 

Next Screen key 
2 

PF3 

Find key 

~0~F~D 

RenxTve 



continued 
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glblreplace: 


083 


117 


ion ma 11*7 iti 

l VAJJ 1.1.9 if 1 


FF1 9 


hightanark: 


017 


010 


010 


~0~H~H 


hightanark: 


033 


133 


OR3 flfiS 17R 

V*>J VAJO 1(w 


F19 key 


highbypeset: 


017 


010 


006 


"0~H"E 


heme: 




033 


117 


170 


g 






Loo 


117 


ion or^Q 11*7 1 ej\ 

i-aJ LOO 11/ 104 


FF1 


ignore 




Loo 


117 


inn rnOQ 11*7 10i 
UoJ UOu XX/ 1Z1 


rt*l H°2 


ignore 




033 


133 




TtiBAJ i ij TL II a | Wqr 
■UJBCL L» AJBJT 


ignore 




n**a 

LOO 


loo 


V-AJ*i I/O 


£3elecu KEy 


ignore 




033 


133 


HRQ (771 17R 


Do key 


ignore 




033 


133 


<TR1 f«7 17R 


F6 key 


ignore 




Loo 


loo 


/Y51 rf7T\ 1*7*3 
UOl \J/U X/O 


F7 key 


ignore 




033 


133 


fiftl ff71 17R 

UDl U/ X lfU 


F8 key 


ignore 




ora*j 

LOO 


loo 


•fV-SO n*-Sn 1*7R 
\JOl*& uou x/o 


P9 key 


ignore 




LOO 


loo 


•fV-SO /YM 1*7R 
\JOl*& UDX X/O 


r iu KEy 


ignore 




ora*j 

LOO 


loo 


r*30 n*?Q 1*7R 
UOrfi UDO x/o 


T?1 1 Trar 

rii wey 


ignore 




LOO 


loo 


VJCl>£ UOfl x/o 


rl£ KEy 


ignore 




LOO 


loo 


ORO fVK 1*7R 
UO£ VJOO X/O 


rlO KEy 


ignore 




LOO 


loo 


noo ofifi 1*7JR 
UDZ UDD X/O 


ri** wey 


insertline: 


033 


117 


ion ot? 117 i«n 

I ^TkV VJOO XX/ XOkJ 


PF1 0 


junptenrark: 


LOO 


117 


1CH OTT-l 11*7 1«V? 

IrTv UOO XX/ XOD 


PF1 


Idlxuidodc : 


OI*7 
L/l/ 


010 


01*4 


"0TT*L 


ldbuufcu.k: 


LOO 


loo 


1*7R 

VJOO VJCl X/O 


P20 key 


left: 




LOO 


1 1*7 
11/ 


104 


left arrow 


left: 




033 


133 


104 


left azrew 


left: 




WI.VJ 






left arrow 


rancweblk: 


<"*1*7 
L/l/ 


/VIA 


vjxo 


~n~T "Tut 


removeblk: 


033 


133 


063 061 176 


F17 key 


mark: 




033 


117 


156 




nextline: 


012 






linefeed 


nextline: 


083 


117 


160 


o 


nextward: 


Loo 


1 1*7 
11/ 


lOl 


1 
i 


prevward: 


Loo 


1 1*7 
11/ 


1 on nm 1 1 1 1 «1 

Xz3J LOO XI/ lOX 


IT 1 1 


readfile: 


Lvo 


cm 






redraw: 


032 






"Z 


replace: 


022 






*R 


replace : 


083 


117 


171 


9 


right: 




083 


117 


103 


right arrow 


right: 




033 


133 


103 


right arrow 


save : 




033 


117 


167 


7 


setcas< 


jsens: 


017 


003 


005 


~0~C"E 


Betdras 




017 


004 


006 


"0~D"E 


setoTertype: 


017 


017 


005 


~CT0~E 


setpwrtype: 


017 


000 


005 


"CTCTE 
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togcasesens : 


083 


117 


120 083 117 122 


FF1 PF3 


togcasesens: 


017 


008 


024 


-crcrT 


togdrawnode: 


017 


004 


024 


TTDT 


tfxjuvtjiLype : 


017 


017 


024 


~0~Q~T 


txxjpwiLype : 


017 


030 


024 


~0~C*T 


top: 


083 


117 


120 083 117 165 


PF1 5 


turtlehl: 


017 


024 


010 


-0-TH 


turtleld: 


017 


024 


014 


•VTTL 


turtleclear: 


017 


024 


003 


~0"T~C 


uldtomark: 


017 


010 


025 




uldturtle: 


017 


G24 


025 


~0T*U 


unbox: 


025 






TJ 


undelline: 


083 


117 


120 033 117 123 


PF1 PF4 


undelward: 


083 


117 


120 033 117 155 


PF1 


UP'- 


083 


117 


101 


lip dLXUW 


up: 


083 


133 


101 


Up aiiui 


uppage: 


083 


117 


165 


5 




083 


133 


065 176 


Rpbv Screen 


wribefile: 


003 


027 




-<rvi 



FtBM/REPDRT GCKMAND6 



insafter: 


006 


Oil 


001 


~F~I~A 


insbefare: 


006 


Oil 


002 


~F~I~B 


budmode: 


006 


002 




~F~B 


qbe: 


006 


025 


002 


"F~U~B 


qwhere: 


006 


025 


027 


~F~trw 


query: 


006 


025 


006 


"F~U"E 


del Tec: 


006 


004 




~F~D 


1 1 lllItT "t*.! 


006 


003 




~F~C 


rollback: 


006 


022 




~F~R 


dupdabe: 


006 


024 


004 


~F~T~D 


pall: 


006 


024 


001 


~F~TA 


F!»ge: 


006 


024 


020 


"F~T"P 


presfc: 


006 


024 


022 


~FT~R 


pickfield: 


006 


013 


025 


-FTCU 


pubfield: 


006 


013 


004 


"F*K~D 


pnexb: 


006 


016 


020 


TTTP 


pprev: 


006 


020 


020 


-p-p-p 


phone: 


006 


006 


020 


"F*F~P 


plasfc: 


006 


014 


020 


"F~L"P 



continued 
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rghcrae 
rglast 
rgnext 

rhone 
rlast 
rnexfc 
rprev: 
prhcme: 
prlast: 
pniext: 
prprev: 
fkme: 
flasfc: 
fnext: 
fnext: 
fnsxt: 
fneocb: 
fprev: 
fprev: 
fprev: 
fpickval: 
flisfcval: 
finsnexb: 
frfuncticn: 
0 



006 006 007 
006 014 007 
006 016 007 
006 020 007 
006 006 022 
006 014 022 
006 016 022 
006 020 022 
006 006 001 
006 014 001 
006 016 001 
006 020 001 
006 006 006 
006 014 006 
006 016 006 
015 

033 117 102 
033 133 102 
006 020 006 
033 117 101 
033 133 101 
006 006 020 
006 026 014 
006 Oil 016 
006 Oil 006 



WINDOW QOMrfANDS 



wrnnp: 

wiirup: 

wLndcmn: 

windcwn: 

winright 

winright 

winleft 

winleft 

windone 

windcne 

a 



033 117 101 
033 133 101 
033 117 102 
033 133 102 
033 117 103 
033 133 103 
033 117 104 
033 133 104 
033 117 156 
015 



~F~F~G 
~F~L~G 
~F~N~G 
"F-P-G 
~F~F~R 
~F~L~R 
~F*N~R 
"F"P-R 
"F~F~A 
"F-L-A 
"FTTA 
-F~P-A 
"FTT 

"F~N~F 
~M 

dom diitM 
dcnm amw 
~p~p~P 

-p-y-p 

■FTL 
-F-I"N 



up arrow 

dCMH tU.'±XJM 

dcwn ul'ixmi 
right 
right 
left 
left 
. - ESC 0 n 
carriage return 



continued 
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HEtU CURSOR ROAM CQvMANDS 



prevmch 
prevmch 
prevmch 
prevmch 
nextmch 
nex.1 ii»*h 
nextmch 
neadrnrh 
honemch 
2 »* ni^i i .* 
select: 

e 



033 117 101 
033 133 101 
033 117 104 
033 133 104 
033 117 102 
033 133 102 
033 117 103 
033 133 103 
010 
020 
015 



UENJ FUNCTION TA3C COMMANDS 



0 



001 
002 
003 
004 



003 015 061 
003 015 062 
003 015 063 
003 015 064 



hEMJ FROvFT LINE TEBMTNAITES 



up 
up 
left 
left 
dcmn 

right 

right 

"H 

T> 

"M 



-cm 

"CTyQ 
-CM4 



roamlast : 

roamlast: 

j,mmnPi i hL.: 

roamfirst: 

prevmerm: 

topmerm: 

temrinabar: 

kiuppiint: 

0 



033 117 101 
033 133 101 
033 117 102 
033 133 102 
025 

024 015 
015 

017 015 020 



up 
up 

derail anew 
dLMSi arrow 
previews menu, 
top menu. 

"M - CR 

-01TP 



End of Chapter 4 
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Chapter 5 
The Terminal Definition File 



Introduction 



This chapter describes the terminal definition file that the Termi- 
nal Definer uses when it builds an encoded Terminal Description 
file. The chapter also explains terminal capabilities, shows a sam- 
ple terminal definition file that describes two terminals, and 
explains their entries. 

The terminal definition file defines: 

• capabilities for terminals on which ALLY can run 

• the character sequences that invoke these capabilities 

The terminal definition file is divided into sections, with each sec- 
tion describing a different terminal. The section for a given ter- 
minal defines the number of lines the terminal displays, the keys 
that move the cursor, the terminal's highlighting and line-draw 
capabilities, and its initialization sequences. 

If there is not a section in the terminal definition file for your ter- 
minal type, you can write one. Look in the file named "termdef ' 
to see if there is a definition section for your terminal type. (On 
UNIX systems, the "termdef ' file is in the "/term/" subdirec- 
tory.) 



Terminal Capability Entries 



There are three types of terminal capability entries: Boolean, 
numeric, and string. The sequences that invoke a terminal's 
characteristics are described in the manufacturer's documentation 
for the terminal. 
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The Terminal Definer utility recognizes a standard notation for 
control characters in capability entries. The caret (") signifies the 
character generated by pressing the control key (<Ctrl>) on a 
terminal along with the key specified (e.g., A H means press the 
control key along with 11 H"). 



Boolean 



Boolean entries specify whether a terminal has a given feature. 
ALLY has two Boolean capability codes: 

bs means that *H backspaces (moves the cursor one space 
to the left). 

im means enter insert mode. 



Numeric 



Numeric entries specify counts and sizes for various terminal 
characteristics. The code is followed by a pound sign (#) and an 
integer number. For example, an entry of ":li#24:" specifies that 
the terminal displays 24 lines. 



String 



A string entry specifies that a capability is available, and provides 
the ASCII character sequence, or string, that invokes the capabil- 
ity. A string-capability code is followed by an equal sign ( = ) and 
the invocation sequence. For example, ":nd="L:" specifies that 
A L moves the cursor one space to the right. 

Some terminals require a delay between executing a function and 
receiving the next character from ALLY. The length of this 
delay in milliseconds must be given as a decimal integer between 
the equal sign and the string. For example, ":cl=50\E[2J:" indi- 
cates that a "clear screen" takes 50 milliseconds on the terminal, 
and is invoked with the ASCII ESCAPE character (represented 
by "\E"), followed by these three characters: [2J. After sending 
this sequence, ALLY sends enough pad characters to provide the 
delay. 
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To list the character sequence for a string entry, use either the 
character itself or its octal code preceded with a back slash (\) . 
For some commonly used ASCII characters that do not have a 
printable letter equivalent, use the following symbols: 

\E ASCII ESCAPE character, octal 033 

\n ASCII line feed (or new line), octal 012 

\r ASCII carriage return, octal 015 

\t ASCII horizontal tab, octal Oil 

\f ASCII form feed, octal 014 

Because the colon (:) is the capability entry delimiter, a colon that 
is part of a string entry must be represented with its octal code 
(\072). The Televideo 925 entry "h5 = \041\EG\072:" illustrates 
the use of a colon within an entry. This entry defines the termi- 
nal sequence for invoking underline and blink highlighting. 



Terminal Capability Codes 



All terminal capability codes consist of two letters. Table 5-1 lists 
the code for each terminal capability, identifies its type, and 
describes the code. Codes for highlighting and line-draw capabili- 
ties are presented later in the chapter. 
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Table 5-1. ALLY Terminal Capability Codes 



Code 


Type 


Description 


al 


string 


Insert a blank line before the cursor line 


be 


string 


Move the cursor one space left (backspace), if not with *H 


bs 


Boolean 


Move the cursor one space left (backspace) with H 


ce 


string 


Clear from the cursor position to the end of the line 


cl 


string 


Clear the entire terminal display 


cm 


string 


Move the cursor to a specific line and column 


CO 


number 


Number of columns displayed on a terminal line 


dc 


string 


Delete one character at the cursor position 


dl 


string 


Delete the line that the cursor is on 


do 


string 


Move the cursor down one line 


ei 


string 


End insert mode and enter overtype mode 


ic 


string 


Insert a character at the cursor position, 






shifting text to the right 


im 


Boolean 


Enter insert mode 


is 


string 


Initialize the terminal for cursor movement 






and screen editing 


ke 


string 


Exit special keypad transmit mode 


ks 


string 


Enter "keypad transmit" mode, where the 






numeric keypad sends special command 






sequences instead of numbers 


li 


number 


Number of lines displayed on a terminal 


nd 


string 


Move the cursor to the right without overwriting text 


pc 


string 


Pad character for delays 






(if not ASCII NUL \000) 


rd 


string 


Downward scroll in a region of the display 


rl 


string 


Left scroll in a region of the display 


IT 


string 


Right scroll in a region of the display 


ru 


string 


Upward scroll in a region of the display 


tc 


string 


Cross-reference to another terminal that 






shares capabilities not listed 






in this terminal's description 


te 


string 


Terminate cursor-motion mode 


ti 


string 


Initialize cursor-motion mode 


up 


string 


Move the cursor up one line 
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Sample Terminal Description File 



Terminal definition files are usually created by defining a terminal 
that has extensive capabilities. You can append sections for addi- 
tional terminals to the file as needed by: 

• defining only the capabilities that differ from the first ter- 
minal defined 

• referencing the first terminal defined (with a "tc=" entry) 

The first terminal defined in ALLY'S terminal definition file is 
the Televideo 925. This terminal requires character positions on 
the screen to store a change in highlighting style. These positions, 
or spaces, cannot be used to display data. This is called per- 
manent highlighting and is associated with a physical area on the 
screen. 

The second terminal defined is the Hazeltine Esprit III because it 
also uses permanent highlighting. In addition, it has line-drawing 
capabilities. Figure 5-1 shows a terminal definition file with two 
sections that describe the Televideo 925 and the Hazeltine Esprit 
III. 

The Televideo 925 section is described first. Note that the Televi- 
deo entries have been separated with blank lines for readability. 
However, the terminal definition file can have blank lines only 
between two sections; there cannot be blank lines within a section. 
Explanations of the capability codes defined in each section follow 
Figure 5-1. 
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© 

) v7H 

©0 



®# Hie Televideo 905 
v7ltvi925 925!televideo 925 :\ (6 



© 



0- 



:li#24: :oo#80:\ 

© © ® 

:bB: :nd=~L: :up=~K: :do=~V: :cnf=\&#- %* :\ 

© © © © © 

:ic=\JBg: :al=\EE: :dc=\EW: :dl=\ER: :ei=\Er: :iin=\Eq:\ 

© Q O © ® 

:oe=\Et: :cl=\£>:\ 

© © 
(24) : is=\Er^3»\e\O47\E:(\&AEX\EL\E>e4\r\20O : \ 

hD=\041\EDO : hl=\O41\038 : h2=\041\EE4 : h3=\041\JEE< : \ 
h4=\041\EE2 : hS=\041\fE\072 : h5=\O41\036 : h7t=\041\En> : \ 

hS=\341\E)\0CO\E<\0CO\B»:^ 

hAF\341\ED \000\E(\000\EE4 : hB=\341\£) \OOO\E(\OOO\0O< : \ 
hC=\341 \E) \000\E (\000\B32 : hD=\341 \£) \000\E (\000\EE\O72 : \ 
hE=\341\E0 \000\E(\000\EE6 :hP=\341\E0 \000\E(\000\EE> : 



# Hazeltine esprit III - similar to the televideo line 
v7lesp3imiEsprit UI:\ 

: is=\EE\ED0\EJ5\E ' \E OvEsADC^\Ebo4 V\2D0\ED\Er\&i\E ! 2\ 

\Be \E\\1"0\E":\ 
: hG=\300\E$\CX»\EjJ : :gc=RH*NL£KJI: :tc=tv!925: 



F002-0912-00 



Figure 5-1. Sample Printer Definition File 
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A Complete Terminal Description Section 



The main components of the Televideo 925 section in the sample 
terminal definition file are: 

• terminal names and editing capabilities 

• initialization sequences 

• highlighting capabilities 

Explanations of the entries and the syntax rules are listed in the 
following pages. The numbers refer to Figure 5-1. 



Terminal Names and Editing Capabilities 



1) A comment can precede or follow each terminal descrip- 
tion. The Terminal Definer considers any line that 
begins with the pound sign (#) in the terminal definition 
file to be a comment. 

2) The first entry in a section contains at least three names 
for a terminal, separated by the vertical bar (I) and ter- 
minated by a colon (:). 

3) The first name must be a two-character field that does 
not contain blanks. Usually this name is a letter followed 
by a digit, in this case, "v7." However, these two char- 
acters can be any that you choose to assign to a terminal. 
This name does not have to be unique within the termi- 
nal definition file. 

4) The second name must be the mnemonic by which 
ALLY and the utilities reference the terminal. This 
should be a relatively sliort name consisting of letters and 
digits, in this case, "tvi925" for the Televideo 925 termi- 
nal. 

5) The third and subsequent names can contain blanks. At 
least one should fully identify the terminal. In 

Figure 5-1, the terminal is also known as "925," and its 
complete name is "televideo 925." 
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6) Each line preceding the last line of a section must end 
with a back slash "\". A back slash signifies that the 
next line is a continuation of the section. The back slash 
must be the very last character on the line; do not leave a 
blank after it. 

7) The remaining entries in a section describe the terminal 
capabilities. Each entry consists of a two-character code 
(e.g., nd) followed by a number or a character string and 
terminated by a colon (:). The order in which the capa- 
bility codes are listed is arbitrary. 

8) The Televideo's display is twenty-four lines long. 

9) You can leave space between fields for readability. 

10) The Televideo's display is eighty columns wide. 

The Televideo can move the cursor: 

11) One space to the left (backspace) with A H. 

12) One space to the right with A L. 

13) One line up with A K. 

14) One line down with 'V. 

15) To a given line and column. (This entry is explained in 
the section, "Options for Cursor Movement Capabilities" 
at the end of this chapter.) 

The next group of codes describes the sequences that invoke the 
insert/delete character and line functions: 

16) Move the text at the cursor position to the right to insert 
a character. 

17) Move the current line down one line to insert a blank 
line. 

18) Delete the character at the cursor position. 

19) Delete the line at the cursor position. 
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20) Enter overtype mode. 

21) Enter insert mode. 

The next codes describe the two strings that: 

22) Clear the display from the cursor position to the end of 
the line. 

23) Clear the whole display at one time. 



I nitialization Sequence 



The initialization sequence contains the characters that ALLY 
sends to a terminal when execution begins. An initialization 
sequence sets up the terminal screen and keyboard for cursor 
movement and other screen editing functions. It should turn off 
unused features such as automatic margins, protected fields, and 
initial highlighting. 

24) The initialization sequence for the Televideo 925: 

• sets the terminal to conversational mode 

• sets highlighting to normal display 

• turns off protect and half-intensity modes 

• turns off the automatic homing of the cursor when it 
gets to the end of the screen 

• turns off monitor mode 

• turns on the function keys for editing 

• sets the terminal's "send" character to carriage return. 



Highlighting Capabilities 



25) The last entries describe the highlighting invocation 
sequences. 
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Highlighting Capabilities 



ALLY uses four types of highlighting — underline, reverse video, 
blink, and altered intensity (higher or lower than normal). 
ALLY can use sixteen combinations of these four types. The 
codes for these are hO through h9, and hA to hF (A through F 
are the hexadecimal digits for decimal 10 through 15). Table 5-2 
lists the ALLY highlighting codes by the type of highlighting they 
produce. 



Table 5-2. ALLY Highlighting Codes 



Highlight Codes 








Reverse 




Altered 


Code 


Type 


Underline 


Video 


Blink 


Intensity 


hO 


string 










hi 


string 


X 








h2 


string 




X 






h3 


string 


X 


X 






h4 


string 






X 




h5 


string 


X 




X 




h6 


string 




X 


X 




h7 


string 


X 


X 


X 




h8 


string 








X 


h9 


string 


X 






X 


hA 


string 




X 




X 


hB 


string 


X 


X 




X 


hC 


string 






X 


X 


hD 


string 


X 




X 


X 


hE 


string 




X 


X 


X 


hF 


string 


X 


X 


X 


X 



For example, the code "hO" sends the terminal sequence that 
turns off all highlighting, and "hA" sends the sequence that pro- 
duces reverse video with altered intensity. Each ALLY highlight- 
ing code turns on the highlighting styles it represents and turns off 
all the others. 
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Permanent Highlighting 



The video attribute codes for the Televideo 925 and Hazeltine 
Esprit III terminals require a space on the display screen. That is, 
one character space on the screen must be reserved for the code 
that turns on highlighting and another space must be reserved for 
the code that turns off highlighting. This is called permanent 
highlighting because it is associated with a physical area on the 
screen. Because permanent highlighting can require up to three 
spaces before and after the highlighted area to mark it, these 
spaces cannot display characters. 

Permanent highlighting marks the beginning and end of an area 
on the terminal screen to be permanently highlighted. If new text 
overwrites text in a permanent area, the new text is highlighted. 



Transient Highlighting 



Another type of highlighting, called transient, is associated with 
the highlighted text and does not require extra display space. 
Text sent to the terminal between the time that transient 
highlighting is turned on and the time that transient highlighting is 
turned off is highlighted. If the text changes, the highlighting 
disappears. Because transient highlighting does not require space 
for marks before and after the highlighted text, the entire area 
can be used to display characters. 



Highlighting Sequences 

The first part of a highlighting entry, called a flag byte, comes 
before the invocation sequence. The flag byte is not sent to the 
terminal, but instead, tells ALLY how a terminal handles 
highlighting. Some terminals must have multiple codes to invoke 
a highlighting style. For example, the Televideo 925 must send a 
code for reverse video and a code for altered intensity to highlight 
an area with reverse video at altered intensity. The SVT-1220, 
however, needs only one code to highlight with reverse video at 
altered intensity. 
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The flag byte tells ALLY whether a highlighting sequence consists 
of a single code or multiple codes. The flag byte for multiple 
highlighting codes tells ALLY which codes are for permanent 
highlighting and which are for transient. 

To calculate the value of the flag byte, sum the octal codes (from 
the list below) in the highlighting sequence, plus the number of 
spaces (0-3) needed to mark the beginning and end of a per- 
manent highlight area. The octal code values that comprise a 
highlighting sequence are: 

\200 Transient-On 
MOO Transient-Off 
\040 Permanent 

The value of the flag byte reflects the number of codes (one to 
three) the highlighting sequence contains. For example, a 
highlighting sequence containing only a transient-on code has a 
flag byte value of octal 200. The flag byte for a sequence contain- 
ing a transient-on code, a transient-off code, and a permanent-on 
code requiring one space to set, has an octal value of 
200+ 100+040+ 1, or 341. Note that there is only one code for 
permanent highlighting (\040). Permanent highlighting remains 
on until the code to turn off highlighting (hO) is sent. 

If the highlighting sequence consists of more than one code, they 
must be in the order listed above. Each code that is followed by 
another code must end with \000. For example, in the entry 
"h8=\341\E)\000\E(\000\EG0:" the first \000 tells ALLY that 
this is the end of the transient-on code and that the beginning of 
the transient-off code follows. If a sequence string must contain 
an ASCII NUL (\000), encode that NUL as \200 to avoid confu- 
sion. 

The following expansions of two of the sixteen highlighting 
sequences for the Televideo 925 terminal illustrate this process. 
The sequence "h2=\041\EG4:" turns on reverse video. The flag 
byte, \041, tells ALLY that the sequence contains a permanent-on 
code requiring one space to set. To highlight text in reverse 
video, ALLY sends 1 \EG4" to the terminal, then sends the text, 
and then sends k '\EG0" to turn off highlighting. (The \EG0 
sequence is defined in the Televideo's terminal definition file for 
the ALLY code that turns off all highlighting, "h0".) 
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The sequence "h8=\341\E)\000\E(\000\EG0:" turns on altered 
intensity. The value of the flag byte, \341, tells ALLY that the 
sequence contains a transient-on part tk \E)", a transient-off part 
"\E(", and a permanent-on part "\EG0" that requires one space 
to mark. To highlight text in altered intensity, ALLY sends to 
the terminal lt \EG0\E)", then the text, then tl E(\EG0". 

Table 5-3 separates the Televideo highlighting sequences to make 
them more readable. 

Table 5-3. Televideo Highlighting Sequences 



Terminal Sequence That Invokes 

Definition Flag 

Code Byte Transient-On Transient-Off Permanent-On 



:h0 


\041 






\EG0 


:hl 


\041 






\EG8 


:h2 


\041 






\EG4 


:h3 


\041 






\EG< 


:h4 


\041 






\EG2 


:h5 


\041 






\EG\072* 


:h6 


\041 






\EG6 


:h7 


\041 






\EG> 


:h8 


\341 


\E)° 
\E)° 
\E)° 
\E)° 
\E)° 
\E)° 
\E)° 
\E)° 


\E(° 
\E(° 
\E(° 
\E(° 
\E(° 
\E(° 
\E(° 
\E(° 


\EG0 


:h9 


\341 


\EG8 


:hA 


\341 


\EG4 


:hB 


\341 


\EG< 


:hC 


\341 


\EG2 


:hD 


\341 


\EG\072* 


:hE 


\341 


\EG6 


:hF 


\341 


\EG> 



* 072 is the octal representation of a colon 
° In the terminal definition entry, this part of the sequence is 
followed by the separator \000. 
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Line-Draw Capability Section 



In addition to the standard Televideo 925 terminal features, the 
Hazeltine Esprit III terminal can produce line-draw characters for 
making boxes with corners on the display. Table 5-4 describes the 
line-draw codes available. 



Table 5-4. Line-Draw Codes 



Line-Draw Codes 



Code 


Type 


Description 


gc 


string 


List of letters that specify 






line-draw characters 


hG 


string 


Initialize line-draw characters and strings 




(used with the characters in gc entry) 



Figure 5-2 shows the section of the sample terminal definition file 
that describes the Esprit. This section lists only an initialization 
sequence and the line-draw sequences, and references the Televi- 
deo 925 for the remainder of its characteristics. We have inserted 
blank lines for readability, but a terminal definition file can con- 
tain blank lines only between sections. 



© 

# Hazeltine esprit; HI - nimilar to the televideo line 
2) •v7lesp3imiEaprLt UI:\ 

(3) : i»=\B2\^\EJf\E' \EOv&AEX\&^ 
W \Ee \£\\1~0\E":\ 

: hG=\300\E$\000\£j( : :gc=FT3EMfttJDKJI: :tc=tvi92S: 

© © © 



Figure 5-2. Hazeltine Esprit III Terminal Section 
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1) The description begins with a comment about the termi- 
nal. 

2) This entry lists the names by which this terminal is 
known. 

3) The Esprit III requires a separate initialization sequence 
to ensure that line-draw mode is off when ALLY initial- 
izes the terminal. 

4) The tl hG" entry has a flag byte that tells ALLY that the 
sequence contains a transient-on code and a transient-off 
code for turning line-draw mode on and off. To draw 
boxes and lines on the Esprit III, ALLY must send it 
"\E$", followed by the letter(s) listed in the tk gc" entry 
to draw the lines, followed by "\E%" to turn off line 
drawing. 



Line-Draw Capability 



5) The "gc" entry lists letters for the eleven line-draw char- 
acters that the Esprit III can produce. The letters that 
represent the line-draw characters must be listed in this 
order: 

1 upper-left corner 

2 upper- right corner 

3 lower-left corner 

4 lower- right corner 

5 left T-bar (intersection of horizontal line with 
the middle of a vertical line to its left) 

6 upper T-bar 

7 right T-bar » 

8 lower T-bar 

9 horizontal line 

10 vertical line 

11 a cross (vertical line and horizontal line both 
intersecting in the middle) 

6) The last entry, "tc=tvi925," tells ALLY to obtain the 
remaining capabilities for the Esprit III from the 
"tvi925" entry. The fck tc" entry, if included in a 
terminal's description, must come last in the section. 
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The "tc" entry references the characteristics of another 
terminal in the terminal definition file. The terminal 
being described shares all of the capabilities of a terminal 
referenced by "tc" except those itemized in the 
terminal's section. ALLY checks the terminal named in 
the "tc" entry for each capability not listed in the 
terminal's description. 

A terminal definition file usually contains a full descrip- 
tion for the terminal with the most capabilities. Sections 
for other terminals that share many of these capabilities 
list only capabilities that are different, and end with a 
"tc" entry. 



Options for Cursor Movement Capability 

This section describes the options for the "move cursor to line X, 
column Y" terminal definition entry, "cm". The cursor move- 
ment options are listed and described in Table 5-5. These options 
are specified after the sequence that signals cursor motion in a 
"cm" sequence. 

A "move cursor" sequence directs a terminal to move its cursor 
to a specified line and column. Terminal manufacturers use dif- 
ferent ways to encode this, so the "cm" terminal definition entry 
must be capable of describing many different formats. The 
manufacturer's documentation for the terminal specifies its 
requirements. 

Some terminals require that the "move cursor" sequence give the 
line first, then the column, while other terminals require the 
opposite. Some terminals number lines and columns beginning 
with zero, while others begin with one. Some require complex 
encodings of the line and column numbers. These are all speci- 
fied with options in the "cm" sequence. 

The "cm" sequence options are marked with percent signs, "%," 
followed by one or more letters that specify the option. The line 
and column numbers are substituted in the "cm" string in place of 
the option when the string is sent to the terminal. 
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Table 5-5. Cursor Movement Options 



Option Description 

%0 The order of the values to be sent out for region scrol- 

ling. 

%r Reverse the line and column output order — send column 

first, then line. By default, ALLY substitutes the line 
number followed by the column number. 

%i Increment the line and column numbers. By default, 

ALLY starts lines and columns at 0; with this option, 
ALLY starts lines and columns at 1. 

%>ab If either the line or the column number is greater than 
the value of the number in the l a' position (expressed in 
octal), then add to that number the value of the number 
in the 'b' position (also expressed in octal) . In the exam- 
ple "%>\010\050," a line value of 5 is left as is, and a 
column value of 12 is converted to 52 (octal 050 is 
decimal 40, plus 12 is decimal 52). 

%n Exclusive-Or the line and column numbers with octal 

140. 

%B Convert the line and column numbers to BCD (Binary 
Coded Digits) before sending them. 

%D For each line and column number: divide by 16, multiply 
the remainder by 2, and subtract the result from the line 
or column number. This is required by the Delta Data 
terminal. 

%% Send a single percent sign. 

The remaining options must be placed in the sequence after any 
of the preceding options. 
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Option Description 

%d Send the line or column number as an integer. For 

example, ALLY sends column 25 as the two characters 

"25." 

%2 Same as %d, but send the number as two digits. For 

example, ALLY sends 2 as "02" and 79 as "79. " 

%3 Same as %d, but send the number as three digits. For 

example, ALLY sends 6 as "006" and 125 as "125." 

%+n Add the octal value of the number in the 'n' position to 
the number and send the result as one character. For 
example, "%+ A" sends 5 as ASCII "F" (5 + 101, 
which is the value of A, = 106, which is the value of F). 

%. Send the number as the ASCII character equivalent of its 

octal value. For example, ALLY sends column 39 as a 
single quote (') since ASCII 39 equals octal 047, and 
octal 047 is a single quote. 



The sequence to move the cursor to line X and column Y on the 
Televideo 925 is "cm = \E=%+ %+ ". It begins with the two 
ASCII characters, ESCAPE and equal sign (\E=), followed by 
the ASCII character whose octal value is the line number added 
to the octal value of an ASCII blank " ", followed by the ASCII 
character whose octal value is the column number added to an 
ASCII blank. For example, ALLY sends "\E= &" to the termi- 
nal to move the cursor to row 0, column 6. 



User-Defined Terminal Definition Files 

If you create separate terminal definition files and store them in a 
different directory, they are preserved when you install a new 
ALLY release. However, if you define a terminal by appending 
its description to the terminal definition file that is shipped with 
ALLY, it is lost when you install a new ALLY release. 

End of Chapter 5 
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Introduction 



The Terminal Definer builds the terminal description file that pro- 
vides ALLY'S portability from terminal to terminal. ALLY, and 
applications built with it, execute on most RS232 ASCII terminals 
that support a "position cursor to x,y" function. The terminal 
description file contains information about the highlighting abili- 
ties, line drawing abilities, and optimizations for each terminal an 
application uses. Figure 6-1 shows the basic operation of the Ter- 
minal Definer. 
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Figure 6-1. The Terminal Definer 
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Terminal Definer Input 



The Terminal Definer utility requires input from: 

• the Format File 

• the terminal definition file 

• the key-definition file 

The sections of the Format File that the Terminal Definer uses 
are described in Chapter 3. The next two sections discuss the 
terminal-definition and key-definition files. 



The Terminal Definition File 



The ALLY terminal definition file provides the Terminal Definer 
with information about the capabilities of the terminals that an 
application uses. The terminal definition file supplied with ALLY 
contains descriptions for several common terminals. If a terminal 
that your application uses is not currently listed in the terminal 
definition file, you can build a terminal definition file for it. 
Chapter 5 describes the terminal definition file. 



The Key-Definition File 



Any ALLY command that can be invoked by a key can be 
assigned to any key or key sequence. (Throughout this manual, 
""key sequence" can be substituted for "key.") These assignments 
are made in a terminal's key-definition file. The key-definition 
file assigns commands to keys by specifying the key's octal code or 
code sequence next to the command mnemonic. Chapter 4 
describes the key-definition file. 



6-2 



UP-13765 



The Terminal Definer Utility 



Terminal Definer Options 



The Terminal Definer displays error or warning messages if there 
are conflicts in the commands assigned to keys (i.e., two or more 
commands assigned to the same key or keys). The Terminal 
Definer issues an error message if there are command-assignment 
conflicts between a global section key and a key in any other sec- 
tion in a key-definition file. The Terminal Definer issues a warn- 
ing message if there are key-assignment conflicts between com- 
mands within a section or between commands in local sections. 

It is acceptable to have conflicts among sections and even within 
sections; however, key-sequence conflicts can cause some com- 
mands to become unavailable to users. The rules for resolving 
key- assignment conflicts are described in Chapter 4. 

Table 6-1 shows the Terminal Definer options for checking con- 
flicts in key assignments in the key-definition file. 

Table 6-1. Terminal Definer Options 



Option Action 

Every key with global keys Compare every key in 

the key-definition file 
for conflicts with the 
keys assigned in the 
two global keys sec- 
tions. 



Each key with every key Compare each key in 

the key-definition file 
with every other key 
in that file for an 
assignment conflict. 

Each key with the same section Compare each key in 

the key-definition file 
with other keys in the 
same section for an 
assignment conflict. 



UP-13765 



6-3 



Chapter 6 



Option 


Action 


No conflict checking 


Do not compare keys 




in the key-definition 




file for assignment 




conflicts. 



Terminal Definer Output 



The output produced by the Terminal Definer is an encoded file 
that contains all of the information needed for an ALLY applica- 
tion to run on a specific terminal. This output file is optimized 
for ALLY execution time. 

The name of this encoded file is the first argument you specify 
when you invoke ALLY. The distributor, application developer, 
or end-user can run the same application on different terminals by 
changing this single argument in the ALLY command. Or, a sys- 
tem manager can build these arguments into operating-system 
command files for each terminal in the system. 

Invoking the Terminal Definer 

from the Dialog 

Figure 6-2 shows the location of the Dialog forms you use to 
invoke the Terminal Definer. 
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Main Menu : ' 
Application . 
Developer's 
Dialog 



Application 
Definition, 
Maintenance, 
& Management 



ALLY Utilities 



AFILE : 
Utilities 



J 



Auxiliary 
Utilities 



Terminal 
Definer Utility 
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Figure 6-2. Dialog Path to the Terminal Definer 



Figure 6-3 shows the Dialog form that you use to run the Termi- 
nal Definer. 
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Terminal Definer Utility 
Facwt, File: <ally}/fannata/allyfmt. (T) 

Description file to build: (IT) 
Terminal name: 
Key-def initial file: (V) 

Terminal definition file: -Cally>/tenn/fcermdef (IT) 
Display conflict checking options: Of/N) N (IT) 



Figure 6-3. Invoking the Terminal Definer 

1) The name of the current Format File is filled in. Type 
<Return> to use this file, or, edit or delete the 
displayed name to use a different Format File. 

Enter the following information in the remaining fields: 

2) Specify a name for the file that is to contain the 
terminal's character mapping information. The file name 
must be compatible with your operating system's naming 
conventions. 

3) Type the ALLY mnemonic from the terminal definition 
file that identifies the terminal for which you are building 
this description file. 

4) Type the name of the file that specifies the key-to- 
command assignments for the terminal named above. 

5) The name of the file that lists terminal capabilities when 
ALLY is shipped is filled in. If you want to use a dif- 
ferent terminal definition file, type in the name of the 
one you want. 

6) Type < Return > to accept the default level of conflict 
checking — that keys are not checked for assignment con 
flicts. The cursor moves to the confirmation field. 

Type "Y<Return>" to display the subform (Figure 6-4) 
that lists the conflict checking options. 
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Terminal Deflner Utility 
Format File: {ally}/fannats/allyfmt 
Description, file to build: 
Terminal name : 
Key-definition file: 

Each key with glchal keys: 
Each key with every key: 
Each key with same section: 
No conflict checking: 



Figure 6-4. Terminal Definer Conflict Checking Options 

Type tl X<Return>" or kk Y<Retum>" in the field of a level of 
conflict checking that you want to select. 

After you enter the required information and use the 'exit action' 
command, the Terminal Definer executes. The cursor moves to 
the lower-left corner of the form while the Terminal Definer runs. 
After the processing is completed, the cursor moves to the menu 
titled Auxiliary Utilities. 

Invoking the Command File 
for the Terminal Definer 



The command file for this utility automatically uses the current 
Format File and terminal definition file. 

The Terminal Definer command file and its arguments are: 



newterm [terminal name] [output file] [keydef file] [option] 



This command requires only the first three arguments. If you 
choose to specify only three arguments, the Terminal Definer does 
not check for conflicts in key assignments. 
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a 



You must specify these arguments: 

terminal name The ALLY mnemonic from the terminal defini- 
tion file that identifies the terminal for which the 
terminal description file is being built. 

The terminal description file produced that con- 
tains the key-mapping information for the termi- 
nal specified by "terminal name." 

The name of the file that contains the command- 
to-key assignments for your keyboard. 

One of the options that specifies the level of con- 
flict checking for key assignments. The Terminal 
Definer options for conflict checking level are 
listed below. 

a compare each key with every other key for a 
conflict in assignment 

g compare each key with the keys assigned in 
the two global sections for an assignment con- 
flict 

n do not check for conflicts in key assignments 

o compare each key with other keys in the 
same set for an assignment conflict. 



Invocation Example 



newterm tvi.925 descripfc tvi925.kdf a 



This example invokes the command file for the Terminal Definer 
to build a terminal description file for a Televideo 925 terminal. 
The description file produced is named "descript." The ALLY 
mnemonic that identifies the Televideo 925 terminal in the termi- 
nal definition file is "tvi925." Its key-definition file is named 
kk tvi925.kdf". The "a" option checks all keys for command 
assignment conflicts. 



output file 

keydef file 
options 
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Terminal Definer Error Messages 



The Terminal Definer produces an error message if it finds: 

• no entry in the terminal definition file for the named termi- 
nal 

• an invalid octal number in the key-definition file (such as 
089) 

• an illegal character (~Q or A S) in the key-definition file 

• a line in the key-definition file that is not in the correct for- 
mat 

• a conflict between two command-to-key assignments 

• an incorrect number of arguments 

• an inaccessible terminal definition file 

End of Chapter 6 
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Introduction 



ALLY applications can use any standard ASCII printer. The 
printer definition file provides the Printer Definer utility with 
information about the features of the printers that ALLY applica- 
tions use. These features include boldfacing and underscoring. 

The Printer Definer uses the printer definition file to create an 
encoded file that identifies a printer to ALLY. ALLY provides a 
printer definition file named "printdef ' that describes several 
printers. (On UNIX systems, this file is in the k 7printers/" 
subdirectory.) Look at this file to see if there is a printer descrip- 
tion for your printer. 

If a printer your application uses is not currently in the printer 
definition file, you can either add its description to the "printdef ' 
file or create a separate printer definition file in a different direc- 
tory. The latter method preserves printer descriptions that you 
create when you install a new ALLY release. The printer defini- 
tion file is very similar to the terminal definition file. Before you 
try to create a printer description for a printer definition file, you 
should read Chapter 5, which explains how to create terminal 
descriptions for a terminal definition file. 

ALLY provides commands that print: 

• the current display image 

• the current page of a form/report 

• all remaining pages of a form/report 

• all pages of a form/report 
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All images, whether a single screen or an entire report, are 
translated from ALLY'S standard internal format to a format suit- 
able for the specified printer. The printer definition file gives 
ALLY information on how to translate display images to print 
files. When a print command is issued, ALLY routes the request 
to the appropriate printer and transforms the material to a print- 
able form by translating: 

• formatting characters (such as newlines and page-breaks) 
from a display format to a format for printing 

• highlighting (such as reverse video) to a form that can be 
printed 

ALLY tries to optimize the print format for the printer's require- 
ments. 



Syntax of the Printer Definition File 

The printer definition file encodes printer features in the same 
way that the terminal definition file encodes terminal features. A 
printer description in the printer definition file starts with a list of 
names, or mnemonics, by which a printer is known (e.g., 
XEROXP for the Xerox 2700 II Laser Printer with portrait font). 
The remainder of the printer description enumerates capabilities 
and the characters necessary to invoke them. 

Figure 7-1 shows the format of printer definition file entries for 
the Xerox 2700 II Laser Printer. There are two descriptions for 
the Xerox 2700: 

XEROXP Portrait font that prints pages that are 63 lines long, 
80 columns wide 

XEROXL Landscape font that prints pages rotated sideways, 63 
lines by 132 columns 
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Xerox 2700 II laser printer with portrait foot 

# Assumes that foot 1 is a ten character per inch fcnt.^-v 

# J3J 
XP IXERCKP lXEStK-2700 laser printer w/ portrait fcnt:\*^~^ 

:\E+P.ALLA012\El\&fi60 ( 15, 15, 15,496\012:f s=X\0l2\E+X\012: \ 
:ff^X:oo^:ll^:scR\Eb:seF=\]Ep:us=\& 1 :ue=\&T: 



# 

# Xerox 2700 II laser printer with landscape font 
# 

XL|XEKKL|X£HK-2700 laser printer w/ l^Ho^rpo font:\ 

: is=\E^. ALLAO12\0D\Bi612, 24, 24, 40,625X012 : f s=~L\012\E+X\012 : \ 

:ff=~L: :co#132: :1±#66: :so=\Eb: :se=\Ep: :us=\&i: :ue=\Ew: 



4 



© 
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Figure 7-1. Sample Printer Definition File 



1) Comment lines begin with a pound sign (#). 

2) A description section begins with the printer's mnemon- 
ics, separated by "I". 

3) Continuation lines within each entry end with "\". 

4) Each printer capability is represented with a two-letter 
code. A capability can be Boolean, numeric, or string 
(see Table 7-1). The manufacturer's documentation for 
the printer specifies the sequences that invoke each capa- 
bility. 

5) Fields are delimited with a colon (:). Fields can be 
separated with spaces for readability. 
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Printer Features 



Printers vary in the way they handle margins, pagination, and 
highlighting. 



Page Margins 



Characters exceeding the printer's maximum line length are 
printed on the next line, starting in column one. Note that this 
can affect pagination. 



Pagination 



To move the printer to the next page, a form feed (also called a 
page eject) normally follows each page that is printed. When a 
page exceeds the printer page length, the extra lines are printed 
on the top of the next physical page. A form feed follows the last 
line on the page. 

The form-feed string causes the printer to go to a new page. If 
this string is set to null (:ff= :), ALLY assumes the printer does 
not provide the form-feed function. In this case, ALLY outputs 
blank lines to reach a new page. It is important to note that there 
is a difference between omitting the form-feed string and setting it 
to null. If you omit the form-feed string, the default value is ~L 
(see Table 7-1). 

Aside from how the printer advances to the next form, you can 
specify a string to pad output with leading and trailing blank pages 
before and after each print job. Even if these strings are not 
specified, ALLY automatically advances to the next form after 
the last page so that the next print job does not start on the same 
page as the previous job. 
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Highlighting 



ALLY supports sixteen highlighting styles for a display. How- 
ever, standard printers are capable of only a few styles of text 
emphasis. Therefore, ALLY supports only two terminal display 
highlighting modes for printed output: reverse video and under- 
line, and the combination of these two. 

Reverse video is translated to boldface, and underline on the 
display is translated to underlining on the printed page. All other 
display highlighting is ignored. 

Highlighting is accomplished in the best way available on each 
printer. For efficiency and visual effect, highlighting is usually 
done by issuing the appropriate start and stop highlighting com- 
mands. Where the string to be highlighted spans multiple print 
lines, ALLY automatically turns off highlighting at the end of 
each line and turns on highlighting again at the beginning of the 
next line. 

These highlighting commands are not available on some printers. 
In this case, ALLY uses a carriage return string to return to the 
start of the line and then overprints the highlighted string. 
Highlighting is not possible on printers that do not have either 
special commands to turn highlighting on and off or an explicit 
carriage return string. In addition, the last character of each line 
cannot be highlighted when the printer supports automatic mar- 
gins. 
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Printer Capability Codes 



Table 7-1 lists each printer capability, identifies its type, and 
describes it. 



Table 7-1. ALLY Printer Capability Codes 



l>dlllc 


type 


noc^rintinn 
L/c5tl 1UL1U11 


am 


Boolean 


Automatic margins 


ap 


Boolean 


Automatic end of page 


be 


string 


Backspace if not *H 


bs 


Boolean 


Backspace with *H 


CO 


number 


Number of columns in a line 


cr 


string 


Carriage return (default A M) 


ff 


string 


Form feed (default X) 


fs 


number 


If printer is a tty, set flag bits (default 0) 


is 


string 


Printer initialization string 


li 


number 


Number of lines on a page 


nl 


string 


Newline character (default 0) 


OS 


Boolean 


Printer overstrikes 


se 


string 


End standout mode 


so 


string 


Begin standout mode 


ue 


string 


End underscore mode 


us 


string 


Start underscore mode 



End of Chapter 7 
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Introduction 



The Printer Definer, shown in Figure 8-1, requires input from the 
Format File and the printer definition file. The printer definition 
file provides the Printer Definer with information about the capa- 
bilities of the printers that your application uses. See Chapter 7 
for information about the printer definition file. 




Invoking the Printer Definer 

from the Dialog 

Figure 8-2 shows the location of the Dialog forms you use to 
invoke the Printer Definer. 
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Main Menu 
Application ' 
Developer's ' 
Dialog 






Application 
Definition, 
Maintenance, ) 
& Management i 






ALLY I 


Jtilities 







AFILE 
Utilities 



T 



Auxiliary 
Utilities 



i 



Printer 
Definer Utility 



L 
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Figure 8-2. Dialog Path to the Printer Definer 



Figure 8-3 shows the Dialog form that you use to invoke the 
Printer Definer. 
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Printer Definer Utility 



Format File: {ally}/fannats/allyfiiit (jT) 

Description file to build: (¥) 
Printer name: (V) 

Printer definition file: {allyVpriiiters/piintdef (T) 



Figure 8-3. Invoking the Printer Definer 

1) The name of the current Format File is filled in. Type 
<Return> to use this file, or, edit or delete the 
displayed name to use a different Format File. 

Enter the following information in the remaining fields: 

2) Specify a name for the printer description file you want 
ALLY to build. This name must be compatible with 
your operating system's naming conventions. 

3) Type the ALLY mnemonic from the printer definition 
file that identifies the printer for which the printer 
description file is being built. 

4) The name of the current printer definition file is filled in. 
Type <Return> to use this file. To use a different file, 
type in the name of the file that lists the capabilities of 
the printer for which you are building the description 
file. 

After you enter the required information and use the 'exit action' 
command, the Printer Definer executes. The cursor moves to the 
lower-left corner of the form while the Printer Definer runs. 
After processing is completed, the cursor moves to the menu titled 
Auxiliary Utilities. 
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Invoking the Command File 

for the Printer Definer 

The command file for this utility automatically uses the current 
Format File and printer definition file. 

The Printer Definer command file and its arguments are: 
newprint [printer name] [output file] 
You must specify for the arguments: 

printer name The ALLY mnemonic from the printer definition 
file that identifies the printer for which the printer 
description file is being built. 

output file The printer description file to be produced for the 
printer specified by "printer name." 



Printer Definer Error Messages 

The Printer Definer produces an error message if it finds: 

• an output file that cannot be opened 

• a printer without an entry in the printer definition file 



End of Chapter 8 
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Managing Printer Output 



Introduction 



Print commands for ALLY applications can be issued either: 

• automatically by any form/report, or 

• explicitly by the user. 

ALLY builds the print file and sends it to the printer with the 
operating system's standard facilities. You tell ALLY how you 
want to handle printing for an AFELE by providing information 
about the following: 

• The printer description file is the encoded file produced by 
the Printer Definer utility that tells ALLY how to interpret 
screen images for the printer that prints your application's 
reports. 

If you have more than one printer, you can choose which 
printer to use for printing your application's forms/reports 
by specifying a different printer description file. You do 
this by modifying the application with the Dialog. 

• The printer output file contains the interpreted screen 
images of your application's reports. This is the default 
destination for form/report output. Each print request to 
this file writes over the previous file contents. The file is 
not printed until you invoke your operating system's print 
command. 

You specify a printer output file for your application 
AFILE with the Dialog. If you do not specify a printer 
output file, the print image is written to a temporary file 
that is deleted when the file is printed. 
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• The spooling information names the destination for ALLY 
print requests, and can be a physical device or a printer 
queue. It can also be the name of a file if you have 
assigned "copy" as the value of the "allyprinter" environ- 
ment variable. (See the section, "Overriding Printer 
Specifications," for information about the "allyprinter" 
variable.) 

You specify spooling information for your AFILE with the 
Dialog and set environment variables with operating system 
commands. 



Spooling 



Translated display images are written to a print file and sent to 
the operating system's print spooler. Images can also be spooled 
to a standard text file that can be edited. 

If spooling devices are available, spooling is the default. ALLY 
provides a program that simulates a spooler for UNIX operating 
systems without print spoolers. The "spoolcmd" file is ALLY'S 
interface to UNIX printers. There are two "spoolcmd" files 
located in the "/printers/" subdirectory: 

spoolcmd for UNIX systems with spooling devices. 

spoolcmd.noq for UNIX systems without spooling devices. 

Follow the steps below if you are not using spooling devices: 

1) Make a backup copy of the "spoolcmd" file by copying 
the file to a file with a different name. For example, 

cd printers 

cp spoolcmd spoolcmd. que 

2) Write the "spoolcmd.noq" file over the "spoolcmd" file 
with the 'copy' command. For example, 

cp spoolcmd.noq spoolcmd 
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ALLY requires a passive spooling device, that is, one that does 
not interpret the characters sent to it. If your spooling device is 
not a passive service, you need to change the printer definition file 
specifications for special and control characters. 



Overriding Printer Specifications 



You can append the contents of the printer output file to a spool- 
ing file and override an application's global printer specification 
by defining an environment variable named "allyprinter." You 
assign a value to the "allyprinter" variable with an operating sys- 
tem command before running an application. 

The "allyprinter" environment variable can be set to one of three 
values: 

none Sends interpreted screen images of your 

application's reports to the printer output file. 

Use "none" when you do not want your output 
to be routed to a printer. Each print request to 
this file writes over the previous file contents. 

copy Sends interpreted screen images of your 

application's reports to the printer output file, 
and then appends the file's contents to the spool- 
ing file. 

The file is not printed until you invoke your 
operating system's print command. The printer 
subsystem continues to append images from the 
printer file to the spooling file until you delete 
the spooling file. 
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queuejname Sends interpreted screen images of your 

application's reports to the printer output file 
and then routes the file to the specified printer 
queue. 

Specify a valid spooling device for queue _name. 
A queue name specified for the value of "ally- 
printer" overrides the default spooling device 
that is displayed in the Dialog's and AMU's Glo- 
bal Printer Information form. 

Neither "none" nor "copy" is case sensitive, though "allyprinter" 
is. The "allyprinter" variable overrides all other printer routing 
information for the application. If the "allyprinter" variable is 
not defined, output is sent to the printer output file and routed to 
the printer or device that is defined for the application. See 
Chapter 1 for more information about environment variables. 



End of Chapter 9 
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Appendix A 
UNIX ALLY Directory Structure 



This appendix lists the subdirectories and files contained in the 
top-level release 2.00 ALLY directory named "ally2_00." 



Subdirectory 



Contains 

Subdirectory File 



Development systems only 



afiles 



allyexe 



bin 



allyedit allyedit.a 

amu amu.a, amu.e, and amu.h 

commen commen.h 

dialog* dialog.a*, dialog.e*, and dialog.h* 

errors errors, e 

storybook start.a, HOURS.A, salary.fx, 
EMPLOYEE. fx, HOURS.fx 

allydevx* 

allyrunx 

amigratx* 

amux 

compactx* 

dmigratx* 

mergex* 

mmigratx 

newmsgx* 

newprntx 

newtermx 

scriptx* 

acompact* 
ally 

allyedit 

amerge* 

amigrate* 

amu 

ascript* 

dialog* 

dmigrate* 
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Subdirectory 



Contains 



Subdirectory File 



Development systems only 



formats 
objects* 
printers 



src* 
term 



include' 1 



mmigrate 
newmsg* 
newprint 
newterm 

allyfmt 

usercode.o* 

DFLT 

LP05 

printdef 

spoolcmd 

spoolcmd.noq 

usercode.in* 

svtlOOc 

svtlOOc.kdf 

svtl210 

svtl210.kdf 

svtl210a 

svtl210a.kdf 

svtl210c 

svtl210c.kdf 

svtl210t 

svtl210t.kdf 

svtl220 

svtl220.kdf 

svt 1220a 

svtl220a.kdf 

svtl220al32 

svtl220c 

svtl220c.kdf 

svtl220cl32 

svtl220t 

svtl220t.kdf 

svtl220tl32 

termdef 
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MS-DOS ALLY Directory 



This appendix lists the file contents of the release 2.00 ALLY 
directory, named "ally2_00." Note that while all ALLY files are 
in a single directory, they are separated by type here. 



Type of File File Name 

* Development systems only 

_____ allyedit.a 

com men. h 

dialog. a*, dialog. e*, and dialog.lr 

errors, e 

hours, a 

start, a 

salary, fx 

employee, fx 

hours, fx 



Executable 



Command file 



allydevx.exe* 

allyrunx.exe 

amigratx.exe* 

compactx.exe* 

dmigratx.exe* 

mergex.exe* 

mmigratx.exe 

newmsgx.exe* 

newprntx.exe 

newtermx.exe 

scriptx.exe* 

acompact.bat* 

ally, bat 

allyedit.bat 

amerge.bat* 

amigrate.bat* 

ascript.bat 

dialog.bat* 

dmigrate.bat* 

install.bat 
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Type of File File Name 

* Development systems only 

install2.bat 

mmigrate.bat 

newmsg.bat* 

newprint.bat 

newterm.bat 



Format File 

Object code for linking to 
3GL driver program* 

Printer definition file 



C-code file for inclusion 
in driver program* 

Terminal definition file 



allyfmt 



usercode.obf 

DFLT 
printdef 



usercode.in' 

pcterm 

pcterm.kdf 

termdef 



Installation information file 



devmsgl.doc 
devmsg2.doc 
devmsg3.doc 
readme.doc 



System file 



aconfig.sys 
sg_ask.com 



End of Appendix B 
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Appendix C 
ALLY Command Mnemonics 



Mnemonic Purpose 







abortappl 


Abort application 


d.UvJI Lld.sK. 


/■A.UUI I ld.SK. 


dUUIll 


/-vuu IlCW 11I1C 


bdelete 


Back delete 


bol 


Beginning of line 


bottom 


tjottom 


box 


tsox 


uuurnuuc 


Diuwse, upud.ic, ueieie rnoue 


clrcasesens 


Clear case sensitive 


clrdrawmode 


Clear draw mode 


clrovertype 


Clear overtype 


clrpwrtype 


Clear powertype 


commit 


Commit 




V^AJlULHCoo W111UUW 


cnfrombuf 


Conv from buffer 


cptobuf 


Copy to buffer 


ctrlchar 


Enter control character 


definewdw 


Define window 


defmacro 


Define macro 


delbol 


Delete to beginning of line 


deleol 


Delete to end of line 


delline 


Delete line 


delrec 


Delete current record 


deltomark 


Delete to mark 


delword 


Delete word 


down 


Down 


downpage 


Down page 


dupdate 


Deferred update 
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Mnemonic Purpose 



col 


ciiu ui line 


exemdn 


nxecuie macro 


exemdd 


mxccuic mdLiu irum ine 


CAIldClKJU 


EZ/All dCLHJIl 


p v 1 1 'j n 1 
CAIlaUpi 


P v 1 1 o r\i"\l ip*q i"ii"iri 
CAIl dpjJllCdlHJIl 


CXllld.sK. 


H Vlt foci/" 

CXIL IdSK. 


expdnuwuw 


cxpdiiu W1I1UUW 


expiouewuw 


\—i v 1 p\ /lp n/i t*ipip"\%i/ 

nxpiuuc wiiiuuw 


LUCICIC 


ruiwdiu ucicic 


fhome 


First field 


find 


Find 


findanddel 


Find and delete 


finsnext 


Insert first record in next group 


flast 


T ast field 


flistval 

LIIoL V ul 


Mflvp to list of values 


fncxt 


1/NCXl LlClU 


fpickval 


Pick from list of values 


fprev 


Previous field 


frfnnrtion 


Invoke loeal fnnetion 


gioirepidce 


vjiuudi rcpidcc 


hightomark 


Highlight to mark 


hightypeset 


Set highlight type 


home 


Home 


homemch 

1 1UI llvll lull 


Home area 


ignore 


Ignore 


insafter 


Insert record after 


insbefore 


Insert record before 


insertline 


Insert line 


jumptomark 


Jump to mark 


khelp 


Help 


kmpprint 


Print menu 
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ALLY Command Mnemonics 



Mnemonic Purpose 



ldtomark 


Line draw to mark 


left 


Left 


loadmacros 

1V/UU 111 CIV* 1 V/J 


I oad macros 


macfmfile 


Macro from file 


mactofile 


Macro to file 


mark 


Set mark 


menu 


Function key choice 


movewdw 


Move window 


nextline 


Next line 


nextmch 


Next area 


nextword 


Next word 


overlayblk 


Overlay block 


pall 


Print all 


phome 


First page 


pickfield 


Copy to field-buffer 


picktask 


Pick task 


plast 


Last page 


pnext 


Next page 


ppage 


Print page 


pprev 

rr 


Previous page 


prest 


Print rest 


prevmch 


Previous area 


prevmenu 


Previous menu 


prevword 


Previous word 


prhome 


First display area 


prlast 


Last display area 


prnext 


Next display area 


prntscrn 


Print screen 


prntvnum 


Print version number 


prompt 


Prompt line 


prprev 


Previous display area 


putfield 


Copy from field-buffer 
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Mnemonic 


Purpose 


nhp 


Oiiptv hv PYPmnlp 
vuci y ivy vvAaiiiL/it/ 


miprv 


Fyppntp fiiiprv 


qwhere 


Query by where clause 


readfile 


Read from file 


redraw 


Redraw 


refresh 


Refresh 


removeblk 


Remove block 


rpnlapp 


Rpnlapp 


resizewdw 


Resize window 


rtxhomp 


Fir^t oroim 


rcrlacf 

1 til dot 


F acf crrm in 

1 rtlJl L til UUU 


1 til 1VA I 


Nfpvt crroim 


rcrnrpv 


Prpvioii^ crroim 


rhomp 

L LlvJHLVv 


Fir^t rpporH 

L 11 Jl 1 V^LUl VJ 


right 


Right 


rlast 


Last record 


rnext 


Next record 


roa m f i r<;t 
1 Uall l L 1 1 ol 


Fir<;t arpa 


rnamlast 


I act arpa 


roll hark 


Rollback 


rnrpv 


Prpvions rpporH 


save 


Save 


savemacros 


Save macros 


scrollwdw 


Scroll window 


select 


Choose from roam area 


setcasesens 


Set case sensitive 


setdelaycnt 


Pause 


setdrawmode 


Set draw mode 


setovertype 


Set overtype 


setpwrtype 


Set powertype 


setrptcnt 


Set repeat count 


shell 


Go to OS command line processor 



C-4 



UP-13765 



ALLY Command Mnemonics 



Mnemonic Purpose 



las iv 


^tart taslr 


tprminatnr 

Ivl 11 1 11 1CLLV/L 


Chnn^p from nrnmnt line 


togcasesens 


Toggle case sensitive 


togdrawmode 


Toggle draw mode 


tncrtrlptaQk' 
lugg i c i d?> iv 


Tncxcrlp ta^k" 

DO LdnlS. 


tntmvprtvrv 

lUtuVVl LV L/e 


TVictctIp nvprtvnp 

1 wlllilc UVCl LV L/C 


tnonu/rtvrv 
lugpwi lvljc 


Tntrtrlp mwprtvnp 


ton 


Tnn 


tfinm pn i i 
lu^jineiiu 


Fir<;t mpnii 
i ii si menu 


tnrtlprlpar 

LL11 Llw^-lV/dl 


Clpar tnrtlp 

" — ' l \_-Cl l LLll L1W 


turtlehl 


Highlight with turtle 


turtleld 


Line draw with turtle 


nIHtnm ark - 

U I Li LUl I L tl L IV 


Frasp linp Hraw 
cLac line ui aw 


lilHtnrtlp 

U1ULL11 


Fra^p linp Hraw with tiirtlp 
i_/i cx^e line ui aw wini lui Lie 


1 1 n hoy 

Li 1 1 L/UA 


VJ11L/WA 


undelline 


Undelete line 


undelrec 


Undelete record 


linHplw/nrrl 


I [nHplptp worH 
i iLieie Le wuiu 


up 


Up 


uppage 


Up page 


windone 


Window-action 


windown 


Window down 


win left 


Window left 


winright 


Window right 


winup 


Window up 


writefile 


Write to file 
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ASCII Character Codes 



@ 


NUL 


00000000 


000 


000 


00 


<§> 


01000000 


100 


064 


40 


A 


SOH 


00000001 


001 


001 


01 


A 


01000001 


101 


065 


41 


B 


STX 


00000010 


002 


002 


02 


B 


01000010 


102 


066 


42 


C 


ETX 


00000011 


003 


003 


03 


C 


01000011 


103 


067 


43 


D 


EOT 


00000100 


004 


004 


04 


D 


01000100 


104 


068 


44 


E 


ENQ 


00000101 


005 


005 


05 


E 


01000101 


105 


069 


45 


F 


ACK 


00000110 


006 


006 


06 


F 


01000110 


106 


070 


46 


G 


BEL 


000001 1 1 


007 


007 


07 


G 


01000111 


107 


071 


47 


H 


BS 


00001000 


010 


008 


08 


H 


01001000 


110 


072 


48 


1 


HT 


00001001 


011 


009 


09 


1 


01001001 


111 


073 


49 


J 


LF 


00001010 


012 


010 


OA 


J 


01001010 


112 


074 


4A 


K 


VT 


00001011 


013 


011 


OB 


K 


01001011 


113 


075 


4B 


L 


FF 


00001100 


014 


012 


OC 


L 


01001100 


114 


076 


4C 


M 


CR 


00001101 


015 


013 


OD 


M 


01001101 


115 


077 


4D 


N 


SO 


00001110 


016 


014 


OE 


N 


01001110 


116 


078 


4E 


O 


SI 


00001111 


017 


015 


OF 


O 


01001111 


117 


079 


4F 


P 


DLE 


00010000 


020 


016 


10 


P 


01010000 


120 


080 


50 


Q 


DC1 


00010001 


021 


017 


11 


Q 


01010001 


121 


081 


51 


R 


DC2 


00010010 


022 


018 


12 


R 


01010010 


122 


082 


52 


S 


DC3 


00010011 


023 


019 


13 


S 


01010011 


123 


083 


53 


T 


DC4 


00010100 


024 


020 


14 


T 


01010100 


124 


084 


54 


U 


NAK 


00010101 


025 


021 


15 


U 


01010101 


125 


085 


55 


V 


SYN 


00010110 


026 


022 


16 


V 


01010110 


126 


086 


56 


w 


ETB 


00010111 


027 


023 


17 


w 


01010111 


127 


087 


57 


X 


CAN 


0001 1000 


030 


024 


18 


X 


01011000 


130 


088 


58 


Y 


EM 


0001 1001 


031 


025 


19 


Y 


01011001 


131 


089 


59 


z 


SUB 


00011010 


032 


026 


1A 


z 


01011010 


132 


090 


5A 


[ 


ESC 


00011011 


033 


027 


1B 


[ 


01011011 


133 


091 


5B 


\ 


FS 


00011100 


034 


02B 


1C 


\ 


01011100 


134 


092 


5C 


\ 


GS 


00011101 


035 


029 


ID 


] 


01011101 


135 


093 


5D 


A 


RS 


00011110 


036 


030 


1E 


A 


01011110 


136 


094 


5E 


— 


US 


00011111 


037 


031 


1F 


_ 


01011111 


137 


095 


5F 




SP 


00100000 


040 


032 


20 


I 


01100000 


140 


096 


60 




I 


00100001 


041 


033 


21 


a 


01100001 


141 


097 


61 




" 


00100010 


042 


034 


22 


b 


01100010 


142 


098 


62 




# 


00100011 


043 


035 


23 


c 


01100011 


143 


099 


63 




$ 


00100100 


044 


036 


24 


d 


01100100 


144 


100 


64 




% 


00100101 


045 


037 


25 


e 


01100101 


145 


101 


65 




& 


00100110 


046 


038 


26 


f 


01100110 


146 


102 


66 




• 


00100111 


047 


039 


27 


0 


01100111 


147 


103 


67 




( 


00101000 


050 


040 


28 


h 


01101000 


150 


104 


68 




) 


00101001 


051 


041 


29 


i 


01101001 


151 


105 


69 






00101010 


052 


042 


2A 


i 


01101010 


152 


106 


6A 




+ 


00101011 


053 


043 


2B 


k 


01101011 


153 


107 


6B 




i 


00101100 


054 


044 


2C 


1 


01101100 


154 


108 


6C 






00101101 


055 


045 


2D 


m 


01101101 


155 


109 


6D 






00101110 


056 


046 


2E 


n 


01101110 


156 


110 


6E 




/ 


00101111 


057 


047 


2F 


o 


01101111 


157 


111 


6F 




0 


00110000 


060 


048 


30 


P 


01110000 


160 


112 


70 




1 


00110001 


061 


049 


31 


q 


01110001 


161 


113 


71 




2 


00110010 


062 


050 


32 


r 


01110010 


162 


114 


72 




3 


00110011 


063 


051 


33 


s 


01110011 


163 


115 


73 




4 


00110100 


064 


052 


34 


t 


01110100 


164 


116 


74 




5 


00110101 


065 


053 


35 


u 


01110101 


165 


117 


75 




6 


00110110 


066 


054 


36 


V 


01110110 


166 


118 


76 




7 


00110111 


067 


055 


37 


w 


01110111 


167 


119 


77 




8 


00111000 


070 


056 


38 


X 


01111000 


170 


120 


78 




9 


00111001 


071 


057 


39 


y 


01111001 


171 


121 


79 






00111010 


072 


058 


3A 


z 


01111010 


172 


122 


7A 






00111011 


073 


059 


3B 


{ 


01111011 


173 


123 


7B 




< 


00111100 


074 


060 


3C 


1 


01111100 


174 


124 


7C 






00111101 


075 


061 


3D 


} 


01111101 


175 


125 


7D 




> 


00111110 


076 


062 


3E 




01111110 


176 


126 


7E 




? 


00111111 


077 


063 


3F 


DEL 


01111111 


177 


127 


7F 
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AFILE Compactor utility 

Format File section, 3-4 

invocation command, 2-7 

invocation command file, 2-7 

text strings, 3-4 
AFILE compatibility 

downward, 1-13, 1-14 

upward, 1-13 
AFILE Merger utility 

Format File section, 3-5 

invocation command, 2-7 

invocation command file, 2-8 

text strings, 3-5 
AFILE Message Builder utility 

directives for message text, 3-7, 3-8 

directives in Format File, 3-7 

Format File section, 3-7 

invocation command, 2-8 

invocation command file, 2-8 

message text numbers, 3-8 

message text strings, 3-7 
AFILE Migrator utility 

Format File section, 3-10 

invocation command, 2-8 

invocation command file, 2-9 

text strings, 3-10 
AFILE naming conventions, 1-8 
AFILE Script Writer utility 

Format File sections, 3-11 

invocation command, 2-9 

invocation command file, 2-9 

text strings, 3-11 » 
ALLY Command Menus, 4-2 
ALLY command mnemonics, 4-2, C-l 

in key-definition file, 4-2 
ALLY development system, 2-4 

invoking the Dialog, 2-5 
with a command, 2-5, 2-6 
with a command file, 2-6 
ALLY directory structure, 1-1 

under MS-DOS, 1-3, B-l 
files in, B-l 

under UNIX, 1-2, A-l 
files in, A-l 

subdirectories of, 1-2, A-l 



ALLY environment variables, 1-3, 1-4 
"allyprinter", 9-3 
changing names of, 1-7 
ALLY execution system, 2-3 
development version, 2-4 
runtime version, 2-4 
ALLY release compatibility, 1-13 
among AFILEs, 1-13 
downward, 1-13, 1-14 
upward, 1-13 
ALLY runtime system, 2-4 
invoking an application 
with a command, 2-4 
with a command file, 2-5 
invoking the AMU, 2-6 
with a command, 2-6 
with a command file, 2-6 
"allyprinter" environment variable, 9-3 
ASCII character codes, D-l 

Boldface, p-3 
Brackets, p-4 

Changing environment variable 

names, 1-7 
Command files 

ALLY, 6-7, 8-4 

for ALLY utilities, 2-7 

invoking ALLY with, 2-1, 2-3 

Printer Definer utility, 8-4 

Terminal Definer utility, 6-7 
Command-to-key assignments 

conflicts in, 4-5, 4-6, 6-6 

key combinations, 4-1 

key-definition file, 4-1 

key series, 4-1 

rules for resolving conflicts in, 4-6 
Commands, ALLY, C-l 

assignments to keys, 4-1 

Command Menus, 4-2 

ignore, 4-6, 4-7 

invoking ALLY with, 2-1, 2-2 

mnemonics, 4-1, 4-2, C-l 
Compatibility 

among ALLY releases, 1-13 
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downward, 1-13, 1-14 

upward, 1-13 
Conventions, p-3 
Cursor-movement options, 
terminal definition file, 5-16, 5-17 

Data Migrator utility 

Format File section, 3-12 

invocation command, 2-9 

invocation command file, 2-9 

text strings, 3-12 
Defining environment variables, 1-6 
Directories, ALLY, 1-1, A-l, B-l 

under MS-DOS, 1-3, B-l 

under UNIX, 1-2, A-l 
Displaying environment variables, 1-5 
Double quotes, p-3 
Downward AFILE compatibility 

AFILE Migrator utility, 1-14 

checking with integrity 
reports, 1-14 

Empty brackets, p-4 
Environment variables 

ALLY, 1-3 

"ally", 1-4 

"allyprinter", 9-3 

defining, 1-6 

displaying, 1-5 

operating system, 1-3 

"TERM", 1-4 

using, 1-5 
Error messages 

Printer Definer utility, 8-4 

Terminal Definer utility, 6-9 

Format File, 3-1 
AFILE Compactor section, 3-4 
AFILE Merger section, 3-5 
AFILE Message Builder section, 3-7 
AFILE Migrator section, 3-10 
AFILE Script Writer sections, 3-11 
changing entry text, 3-3 
comments in, 3-3 
Data Migrator section, 3-12 
delimiter characters, 3-2 
directives for message text, 3-7, 3-8 



directives for paths to message 
A FILEs. 3-9 
first section (set 0), 3-2 
Macro Utility section, 3-13 
Printer Definer section, 3-14 
sections of, 3-2, 3-3 
set delimiters, 3-3 
syntax of entries, 3-3 
Terminal Definer section, 3-14 

Help and error AFTLEs, 1-8 
Highlighting, 7-5 
Highlighting sequences 
flag bytes in, 5-11, 5-12 
sample 
(Esprit m), 5-14 
(Televideo 925), 5-13 

Input files, printer definition, 7-1 

Invocation command 
AFILE Compactor utility, 2-7 
AFILE Merger utility, 2-7 
AFILE Message Builder utility, 2-8 
AFILE Migrator utility, 2-8 
AFILE Script Writer utility, 2-9 
Data Migrator utility, 2-9 
Macro Utility, 2-10 
Printer Definer utility, 2-10 
Terminal Definer utility, 2-10 

Invocation command file 
AFTLE Compactor utility, 2-7 
AFILE Merger utility, 2-8 
AFTLE Message Builder utility, 2-8 
AFTLE Migrator utility, 2-9 
AFTLE Script Writer utility, 2-9 
Data Migrator utility, 2-9 
Macro Utility utility, 2-10 
Printer Definer utility, 2-10, 8-4 
Terminal Definer utility, 2-11, 6-7 

Invoking ALLY, 2-1, 2-3 
with a command, 2-1, 2-2 
with a command file, 2-1, 2-3 

Invoking ALLY utilities, 2-7 
AFILE Compactor, 2-7 
AFTLE Merger, 2-7 
AFTLE Message Builder, 2-8 
AFTLE Migrator, 2-8 
AFILE Script Writer, 2-9 
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Data Migrator, 2-9 

Macro Utility, 2-10 

Printer Defirter, 2-10, 8-1, 8-4 

Terminal Definer, 2-10, 6-4, 6-7 

with a command, 2-7 

with a command file, 2-7 
Invoking the AMU, 2-6 

with a command, 2-6 

with a command file, 2-6 
Invoking the Dialog, 2-5 

with a command, 2-6 

with a command file, 2-6 

Key-definition file, 4-1, 4-2 
command-to-key assignments, 4-1 
comments in, 4-7 

conflicts in key assignments, 4-5, 6-6 

rules for resolving, 4-6 
flag definitions, 4-3 
form/report commands, 4-4 
format of, 4-2, 4-3 
global commands, 4-4 
global sections, 4-3 
ignore command, 4-7 
input to the Terminal Definer, 6-2 
local section, 4-4, 4-5 
making commands unavailable, 4-8 
menu cursor roam commands, 4-5 
menu function task commands, 4-5 
menu prompt line exit 
commands, 4-5 
sample (SVT-1220), 4-9 
scroll percentage, 4-3 
sections of, 4-2, 4-3 
syntax of, 4-2 
text editing commands, 4-4 
user-defined, 4-9 
window commands, 4-4 

Library AFILEs, see "Message 

AFILEs," 1-8 
Line-draw capability 

ALLY codes for, 5-14 

entries for, 5-15 

in terminal definition file, 5-15 

Macro Utility 
Format File section, 3-13 



invocation command, 2-10 
text strings, 3-13 
Managing printer output, 9-1 
"allyprinter" variable, 9-3 
overriding global settings, 9-3 
printer description file, 9-1 
printer output file, 9-1 
spooling, 9-2, 9-4 
Message AFILEs 
changing paths to, 1-10 

with directives, 1-11 

with the Dialog, 1-10, 1-11 
directives for 

application paths, 3-9 

default paths, 3-9 
paths to application, 1-11 

Operating system environment 
variables, 1-3 

Page margins, 7-4 
Paths to application message 
AFILEs, 1-11 
Printer capabilities 
ALLY codes for, 7-6 
form feed, 7-4 
highlighting, 7-6 
page margins, 7-4 
pagination, 7-4 
types of entries, 7-3 
Printer capability codes, 7-3 
printer definition file, 7-3 
Printer Definer utility, 7-1 
command file, invocation 
example, 8-4 
error messages, 8-4 
Format File section, 3-14 
input files 
Format File, 8-1 
printer definition, 7-1, 8-1 
invocation command, 2-10 
invocation command file, 2-10 
invoking 
from the Dialog, 8-1, 8-2 
with a command, 2-10 
with a command file, 2-10, 8-4 
output file, 8-1 
printer description, 8-1,9-1 
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text strings, 3-14 
Printer definition file, 7-1 

capability entries, 7-3 
types of, 7-3 

comments in, 7-3 

continuation lines, 7-3 

form feed, 7-4 

landscape font, 7-2 

portrait font, 7-2 

Printer Definer utility, 7-1 

sample (XEROX 2700 II), 7-2 

sections in, 7-3 

syntax of, 7-3 
Printer description file, 8-1, 9-1 
Printer highlighting, 7-5 

boldface, 7-5 

reverse video, 7-5 

underline, 7-5 
Printer output file, 9-1 
Printer spooling, 9-2, 9-4 

Running an AFILE 
entry point to application, 2-5 
reusing macro files, 2-5 
with a command, 2-4 
with a command file, 2-5 
with a debug log, 2-5 

Single quotes, p-3 

Space, p-4 

Square brackets, p-4 

Terminal capabilities 
ALLY codes for, 5-4 

highlighting, 5-10 

line-draw, 5-14 
cursor movement options, 5-16, 

5-17 

highlighting, 5-10 
highlighting sequences, 
flag byte in, 5-11, 5-12 
line-draw, 5-14 
permanent highlighting, 5-11 
transient highlighting, 5-11 
types of entries, 5-1 

boolean, 5-2 

numeric, 5-2 

string, 5-2 



Terminal capability codes, 5-3, 5-4 
Terminal Definer utility 
command file, 6-7 

conflict-checking options, 6-8 

invocation example, 6-8 
conflict checking options, 6-6 

each key with every key, 6-3 

each key with the same section, 6-3 

every key with global keys, 6-3 

no conflict checking, 6-3 
error messages, 6-9 
Format File section, 3-14 
input files, 6-1 

Format File, 3-14, 6-1 

key-definition file, 6-2 

terminal definition file, 6-2 
invocation command, 2-10 
invoking, 6-4 

from the Dialog, 6-4 

with a command, 2-11 

with a command file, 2-11, 6-4, 6-7 
options for conflict checking, 6-3, 6-7 

each key with every key, 6-3, 6-8 

each key with the same section, 6-3, 
6-8 

every key with global keys, 6-3, 6-8 

no conflict checking, 6-3, 6-8 
output file, 6-4 

terminal description, 6-4 
text strings, 3-14 
Terminal definition file, 5-1 
ALLY codes for line-draw, 5-14 
ALLY highlighting 

capabilities, 5-9, 5-10, 5-11, 5-14 

codes, 5-10 

sequences, 5-11 
blank lines in, 5-5 
boolean entries, 5-2 
complete terminal description, 5-7 
cursor-movement entries, 5-16 
editing capability entries, 5-7 
initialization sequence, 5-9 
line-draw entries, 5-14, 5-15 
numeric entries, 5-2 
sample 

(Hazeltine Esprit m), 5-14 
line-draw section, 5-14 
(Televideo 925), 5-5 
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sections in, 5-1, 5-5 
string entries, 5-2 

terminal capability entries, 5-1, 5-2 
cursor movement, 5-8, 5-16 
highlighting sequence, 5-6, 5-13 
initialization sequence, 5-9 
input to the Terminal Definer, 6-2 
line-draw, 5-15 
Terminal Definer, 6-2 
terminal name in, 5-7 
types of entries, 5-2 
user-defined, 5-18 
Terminal description file, 
output from the Terminal Definer, 6-4 
Terminal highlighting sequences, 5-10 
flag bytes in, 5-11, 5-12 
sample 
(Televideo 925), 5-6, 5-13 
Trunk AFTLEs, 1-9 
paths to message AFTLEs, 1-9 

Upward AFILE compatibility 
AFILE Compactor utility, 1-13 
AFTLE Migrator utility, 1-13 

Using environment variables, 1-5 
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